pulser — Claude Code plugin: what it does, how to install

# 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)*