pulser
Lint and diagnose Claude Code SKILL.md files against Anthropic's 8 best-practice rules. Scans frontmatter, description quality, file size, g
Open source Repository Open in the app JSON README (API)
About
Lint and diagnose Claude Code SKILL.md files against Anthropic's 8 best-practice rules. Scans frontmatter, description quality, file size, gotchas, allowed-tools, structure, conflicts, and usage hooks. Auto-classifies skill types and generates fix prescriptions. Installs as a skill — say "check my skills" or /pulser to run
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- thestack-ai
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 18
- Forks
- 1
- Open pull requests
- 1
- Last push
- 2026-06-30T02:54:39Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
thestack-ai/pulser/pulser
README
# pulser — SKILL.md Linter for Claude Code
<p align="center">
<img src="docs/banner.svg" alt="pulser — Diagnose. Prescribe. Fix." width="100%">
</p>
<p align="center">
<a href="https://thestack-ai.github.io/pulser/">Website</a> ·
<a href="https://www.npmjs.com/package/pulser-cli">npm</a> ·
<a href="./README.ko.md">한국어</a>
<br><br>
<a href="https://github.com/TheStack-ai/pulser/actions/workflows/ci.yml"><img src="https://github.com/TheStack-ai/pulser/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://www.npmjs.com/package/pulser-cli"><img src="https://img.shields.io/npm/v/pulser-cli?color=10b981" alt="npm"></a>
<a href="https://www.npmjs.com/package/pulser-cli"><img src="https://img.shields.io/npm/dm/pulser-cli?color=06b6d4" alt="downloads"></a>
<a href="https://github.com/TheStack-ai/pulser/blob/main/LICENSE"><img src="https://img.shields.io/github/license/TheStack-ai/pulser" alt="license"></a>
<a href="https://github.com/TheStack-ai/pulser"><img src="https://img.shields.io/github/stars/TheStack-ai/pulser?style=social" alt="stars"></a>
<a href="https://github.com/rohitg00/awesome-claude-code-toolkit"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Claude Code Toolkit"></a>
<a href="https://github.com/marketplace/actions/pulser-claude-code-skill-linter"><img src="https://img.shields.io/badge/Marketplace-Pulser-10b981?logo=github" alt="GitHub Marketplace"></a>
</p>
"Check my skills." Diagnose, classify, prescribe, and fix — without leaving the conversation.
```
$ pulser
pulser v0.4.0
54 skills scanned · Score: 89/100
✓ 48 healthy ⚠ 4 warnings ✗ 2 errors
Top issues:
cardnews — No Gotchas, no allowed-tools
geo-audit — 338 lines, single file
💊 Rx #1 — cardnews
[GOTCHAS] Add Gotchas section
Why: Anthropic's highest-ROI improvement
Template:
## Gotchas
1. Validate output against conventions
2. Check scope — don't over-generate
Fix type: AUTO
```
## What it does
pulser scans your `SKILL.md` files against 8 diagnostic rules derived from Anthropic's published principles in ["Building Claude Code: How We Use Skills"](https://code.claude.com/docs/en/skills):
| Rule | What it checks |
|------|---------------|
| `frontmatter` | Required `name` and `description` fields |
| `description` | Trigger keywords, "Use when" pattern, length |
| `file-size` | SKILL.md under 500 lines |
| `gotchas` | Gotchas section with failure patterns |
| `allowed-tools` | Tool restrictions appropriate for skill type |
| `structure` | Supporting files for large skills |
| `conflicts` | Trigger keyword overlap between skills |
| `usage-hooks` | Skill usage logging hook installed |
Each skill is auto-classified by type (analysis, research, generation, execution, reference) with confidence scoring. Prescriptions are tailored to the detected type.
## Install
```bash
npm install -g pulser-cli
```
On install, pulser registers itself as a Claude Code skill — say "check my skills" or `/pulser` to run it conversationally.
## Usage
### In Claude Code
Just say it:
```
check my skills
```
Or use the slash command:
```
/pulser
```
Claude runs the diagnosis, summarizes results, and offers to fix issues — all within the conversation.
### In terminal
```bash
# Scan default path (~/.claude/skills/)
pulser
# Scan a specific directory
pulser ./my-skills/
# Scan a single skill
pulser --skill reasoning-tracer
# Auto-fix issues with backup
pulser --fix
# Rollback the last fix
pulser undo
# JSON output (for CI/automation)
pulser --format json
# Markdown report
pulser --format md
# Treat warnings as errors
pulser --strict
# Disable TUI animation
pulser --no-anim
```
## Eval — Skill Testing
New in v0.4.0: test your skills against real inputs.
```bash
pulser eval
```
Write `eval.yaml` next to your `SKILL.md`:
```yaml
tests:
- name: "catches bugs"
input: "Review: function add(a,b) { return a - b }"
assert:
- starts-with: "The bug"
- contains: "subtract"
- min-length: 30
```
pulser runs each test through `claude -p`, checks assertions, and tracks regressions automatically.
```
$ pulser eval
reviewer (2 tests)
✓ catches bugs 320ms
✓ passes clean code 280ms
2 passed · 0 failed · 0.6s
```
Supported assertions: `contains`, `not-contains`, `starts-with`, `ends-with`, `min-length`, `max-length`, `matches` (regex).
### Exit Codes (eval)
| Code | Meaning |
|------|---------|
| `0` | All tests passed |
| `1` | Failures found |
| `3` | Regression detected (previously passing test now fails) |
## Core Pipeline
1. Diagnose — Scan and classify issues across 8 rules
2. Prescribe — Explain why it matters, provide ready-to-use templates
3. Fix — Auto-apply safe structural fixes with full backup
4. Eval — Test skills against real inputs, track regressions
5. Rollback — Instant undo, your safety net
## Exit Codes
| Code | Meaning |
|------|---------|
| `0` | All rules passed |
| `1` | Errors found |
| `2` | Warnings found (with `--strict`) |
## Patient Monitor TUI
When running in a TTY terminal, pulser displays a hospital-style patient monitor with real-time waveform animation:
- Green ECG — Skills being scanned
- Green capnography — Pass/warn/fail counts
- Cyan plethysmograph — Health score
- Yellow respiratory — Prescription count
Disable with `--no-anim` or pipe to a file.
## License
MIT — [TheStack-ai](https://github.com/TheStack-ai)
## Featured in
- [GitHub Marketplace — Pulser Action](https://github.com/marketplace/actions/pulser-claude-code-skill-linter)
- [Awesome Claude Code Toolkit](https://github.com/rohitg00/awesome-claude-code-toolkit)
- [Anthropic Plugin Directory](https://platform.claude.com) *(under review)*