Claude Codeスキルの診断用CLIを作成しました — 私が見逃した8つのルールが検出した点はこちら

interface ClassificationResult {
  type: SkillType;
  confidence: number;
  signals: Signal[];
}

type SkillType =
  | "coding"
  | "writing"
  | "workflow"
  | "diagnostic"
  | "integration"
  | "meta";

The classifier looks at frontmatter fields, body keywords, code block density, and structural patterns. A skill with many ` ```
{% endraw %}
bash {% raw %}`ブロックと「test」、「build」、「deploy」のような単語を含むスキルは、`{% endraw %}coding{% raw %}`として高い信頼度で分類されます。「tone」、「audience」、「draft」といった言葉を含むスキルは、`{% endraw %}writing{% raw %}`に分類されます。

**分類が重要な理由：各タイプには異なる処方があります。** 例が欠けているコーディングスキルは重大な失敗です — Claudeは正確な入力/出力の変換を理解する必要があります。例が欠けているワークフロースキルは警告です。同じルールですが、重大度が異なり、修正も異なります。endraw %}{% raw %}``bash
$ npx pulser-cli --skill my-tdd-skill.md

  ┌─────────────────────────────────────────┐
  │  PULSER v0.3.1 — スキル 診断       │
  │  診断. 処方. 修正.              │
  └─────────────────────────────────────────┘

  スキャン中: my-tdd-skill.md
  分類: コーディング (信頼度: 0.92)

  ■ frontmatter-必須    合格
  ■ 説明-品質     警告  説明 は 8 文字 — 短すぎます 信頼できる ルーティング
  ■ トリガー-明確さ         失敗  トリガー 条件 が見つかりません フロントマター または 本文
  ■ 指示-構造   合格
  ■ 競合-検出      合格
  ■ 例-カバレッジ        失敗  0 例 が見つかりました — コーディング スキル が必要です ≥2
  ■ 範囲-境界        合格
  ■ 依存関係-チェーン        スキップ  (実験的)

  2 問題 が見つかりました. 実行 with --fix で 自動-修正.

## ステップ 3: 処方、 合格 または 失敗

**pulser は生成します タイプ-特定の 修正 提案 を行います 一般的な エラーメッセージ — これが 診断 ツール と リンター を分ける 理由です.** 私が評価した すべての 競合者 は同じ アプローチ: スキャン、 合格 または 失敗、 停止. それは’リンターです。私は’欲しくなかった リンター. 私は 医者が欲しかった.

pulser が問題を見つけると、 現在の 状態、 提案された 修正、 および その修正が なぜ そのスキル’のタイプに適切であるかを示す処方を生成します。 あいまいな説明を持つ`コーディング`スキルは、同じ問題を持つ`ライティング`スキルとは異なる言語を得ます:

```bash
$ npx pulser-cli --fix

  my-tdd-skill.mdの処方:

  1. 説明-品質 (警告)
     現在:  "TDDのこと"
     提案: "コーディングタスクを開始する際に使用 — テストファースト開発で赤-緑-リファクタサイクルを強制します。トリガー: ’テストを書く’、
                ’TDD’、 ’テスト ファースト’。"
     → 自動修正が利用可能です。バックアップが作成されます。

  2. トリガー-明確さ (失敗)
     現在:  (なし)
     提案: フロントマターにトリガーブロックを追加:
               triggers: ["TDD", "test  
first", "write tests", "red green refactor"]
     → 自動修正が利用可能です。バックアップが作成されます。

  修正を適用しますか？ [y/N]

**すべての修正は、何かを書く前にタイムスタンプ付きのバックアップを作成します。** ファイルは `.pulser/backups/{timestamp}/` に保存され、1つのコマンドで元に戻すことができます。最初に正確な差分を表示せずに何も変更されることはありません。

## ステップ 4: アンドゥシステム

修正エンジンは、完全なロールバックサポートを持つアトミック書き込みを使用します。この教訓は、データベースのマイグレーションを展開することで学びました: **もしあなたがそれを'undo it, あなたは それを'自動化すべきではありません。**

```bash
$ npx pulser-cli undo

  バックアップセットが1つ見つかりました:
  [1] 2026-03-15T14:32:00Z — 2ファイルが修正されました
      my-tdd-skill.md (説明 + トリガーが追加されました)
      debug-workflow.md (例のセクションが追加されました)

  バックアップを復元しますか [1]? [y/N] y

  ✓ my-tdd-skill.md を復元しました
  ✓ debug-workflow.md を復元しました
  バックアップは .pulser/backups/2026-03-15T143200/ に保持されました。

アンドゥシステムはバックアップを読み込み、ファイルが期待されるパスにまだ存在することを検証し、一時ファイルに書き込み、その後アトミックに名前を変更します。**もしプロセスが書き込み中に死んだ場合、あなたは'end up with a half-written skill file.** これは マークダウン ファイルに対して 偏執的 に聞こえますが、 シェル スクリプトでの部分的な書き込みは 私の 設定ファイルを 十分に破損させた ので、 私は今 アトミック 書き込みを 交渉不可能なものとして扱っています。

## ステップ 5: 誰も 求めていなかった TUI （しかし 誰もが覚えている）

pulser は EtCO2-スタイルの 患者モニター アニメーションを表示します 、 スキャン中に — 端末を横切る 波形を リアルタイムでトレースします、 まさに 病院の バイタルサイン モニターのように。 これは 必要でしたか？ いいえ。 **それは ツールを 十分に記憶に残るものにしましたか ？ 3人の人が アニメーションについて 尋ねる前に ツールが実際に何をするのかを 尋ねましたか？ はい。**

``{% endraw %}{% raw %}`bash
$ npx pulser-cli --all

  ╭──────────────────────────────────────────╮
  │  ♥ PULSER — Skill Vitals                 │
  │  ╱╲    ╱╲    ╱╲    ╱╲                    │
  │ ╱  ╲__╱  ╲__╱  ╲__╱  ╲__                │
  │                                          │
  │  スキル: 23  健康: 9  警告: 8      │
  │  重要: 6  修正可能: 12                │
  ╰──────────────────────────────────────────╯

`{% endraw %}--no-anim{% raw %}` フラグは、CIパイプラインやANSIエスケープコードをサポートしない端末のためにアニメーションを無効にします。私はClaude Codeの開発者向けのDiscordサーバーでツールをデモしましたが、アニメーションは診断出力よりも即座に多くの質問を生み出しました。記憶に残るUIは配布戦略です。

## ステップ 6: すべてのワークフローのための出力形式

pulserは、異なるワークフローが異なるデータ形状を必要とするため、3つの出力形式をサポートしています。デフォルトは人間が読みやすい端末出力です。`{% endraw %}--format json{% raw %}` は、他のツールにパイプするのに適した厳密なスキーマを出力します。`{% endraw %}--format md{% raw %}` は、リポジトリにコミットできるマークダウンレポートを生成します。

`{% endraw %}{% raw %}``bash
# 人間-可読 （デフォルト)
$ npx pulser-cli

# JSON は 他の ツールに パイプするためのものです
$ npx pulser-cli --format json | jq '.issues[] | select(.severity == "error")'

# Markdown for documentation
$ npx pulser-cli --format md > skill-health-report.md

JSON スキーマ は パッチ バージョン 間で 安定しています。 私は それを 使用します 前-コミット フック の中で 、それは コミットを ブロックします もし 何か コア-ティア ルール が 失敗した場合:

``{% endraw %}{% raw %}`bash
#!/bin/bash
# .git/hooks/pre-commit
ISSUES=$(npx pulser-cli --format json --strict 2>/dev/null | jq '.summary.errors')
if [ "$ISSUES" -gt 0 ]; then
  echo "pulser: $ISSUES スキルエラーが見つかりました。詳細を確認するには 'npx pulser-cli' を実行してください。"
  exit 1
fi

**pulserを前コミットフックとして実行することは、壊れたスキルがメインブランチに到達しないことを意味します。** スキャンは20スキルで4秒未満で完了し、コミットを目立って遅くすることはありません。

## ステップ7: ビルドパイプライン

プロジェクト全体はTypeScriptで、tsupを使用して単一のESMファイルにバンドルされています。合計4つのランタイム依存関係があります:

`{% endraw %}{% raw %}``json
{
  "name": "pulser-cli",
  "version": "0.3.1",
  "type": "module",
  "bin": { "pulser": "./dist/index.js" },
  "dependencies": {
    "commander": "^12.0.0",
    "gray-matter": "^4.0.3",
    "chalk": "^5.3.0",
    "boxen": "^7.1.1"
  }
}

**gray-matter は フロントマターを 解析します、 commander は CLI 引数を 処理します、 chalk と boxen は ターミナルの フォーマットを 処理します。** 他のすべては 標準 ライブラリです。 合計 バンドル サイズは 847KB で 、依存関係を含みます。 Node 18+ が 唯一の ランタイム 要件です。

``{% endraw %}{% raw %}`bash
# グローバルにインストール
npm i -g pulser-cli

# またはインストールせずに実行
npx pulser-cli

## 私が異なることをするなら

**私は8つのルールではなく3つのルールで出荷すべきでした。** 私は包括的に感じたかったので8つのルールで開始しました。実際には、3つのコアルールが実際の問題の80%をキャッチします。推奨ティアはニュアンスを追加しますが、基本的な動作を望むユーザーにはノイズも追加します。私はコアのみを出荷し、残りは `{% endraw %}--full{% raw %}` フラグの後ろにゲートを設けるべきです。

**分類器にはもっとトレーニングデータが必要です。** 私の信頼スコアは、自分のスキルファイルと小さなオープンソースの例のセットに対してキャリブレーションされています — 合計約50のスキルです。分類器は一般的なパターン（TDDスキル、ライティングスキル、ワークフロー自動化）にはうまく機能しますが、珍しいスキルタイプには低い信頼スコアを生成します。信頼できる信頼値を得るには、最低でも200の多様なスキルが必要です。

**私は修正エンジンが堅実になる前にTUIアニメーションに過剰投資しました。** 波形アニメーションを構築するのに丸一日かかりました。その間、処方エンジンにはバグがあり、`{% lass="nx">endraw %}triggers{% raw %}` フィールドは、すでに本文にトリガーキーワードが埋め込まれているスキルに関連付けられていました — これは初期のユーザーを混乱させる誤検知でした。アニメーションは記憶に残りますが、正確さが最優先です。

## 数字

### コスト比較

| アプローチ | コスト | 最初の結果までの時間 |
|----------|------|---------------------|
| 手動スキルレビュー | $0 | 20スキルで2〜3時間 |
| pulserスキャン | $0 | 20スキルで4秒 |
| Claudeにスキルをレビューさせる | ~$0.03/スキル | スキルごとに30秒 |
| カスタムバリデーションの構築 | $0 + 8〜16時間の開発時間 | 変動 |

### スキャンパフォーマンス

| メトリック | 値 |
|--------|-------|
| 1秒あたりのスキルスキャン数 | ~5 |
| 平均修正生成時間 | 200ms |
| バックアップ + 原子的書き込み | <50ms/ファイル |
| 合計バンドルサイズ | 847KB |
| ランタイム依存関係 | 4 |
| 診断ルール | 8 (3つのコア + 4つの推奨 + 1つの実験的) |

## FAQ

### pulserは私のスキルファイルを無断で変更しますか？

いいえ。 `{% endraw %}--fix{% raw %}` フラグは、提案された変更をすべて表示し、書き込み前に明示的な確認を必要とします。すべての変更は、元のファイルに触れる前に `{% endraw %}.\pulser/backups/{timestamp}/{% raw %}` というタイムスタンプ付きのバックアップを作成します。変更は `pulser undo` で復元できます。デフォルトでは何も破壊的ではありません.

### pulser は どのように 良い "スキル" が どのように 見えるか?

それは Anthropic'の公開されたスキル品質原則を実行可能なルールとして実装しています。フロントマターのチェックは、文書化されたClaude Codeスキルスキーマに従います。説明の品質ルールは、最小文字数、トリガーキーワードの存在、アクション動詞の密度に基づく特異性スコアリングなどの測定可能なヒューリスティックを使用します。それは'の 意見を持っていますが 、公開された 文書に基づいています、 個人的な 好みではありません。

### pulser は サブディレクトリ や カスタム ロケーション で スキル と 一緒に 動作しますか?

はい。 デフォルトでは それは `~/.claude/skills/` と 任意の プロジェクト-レベル `.claude/skills/` ディレクトリ をスキャンします。 任意の パスを指定できます: `npx pulser-cli /path/to/my/skills/`。 `--skill` フラグは 単一の ファイルをスキャンします: `npx pulser-cli --skill my-skill.md`。

### CI/CDで pulser を使用できますか?

はい。 機械-可読な 出力には `--format json` を使用し 、エラーが見つかった場合は `--strict` で コード 1 で終了します。 `--no-anim` フラグは 非対話型 環境のために TUIを無効にします。 上記の プレコミット フックの例を参照してください。

### pulser と 一般的な マークダウンリンターの違いは何ですか？

マークダウンリンターは構文をチェックします。 **pulserは意味論をチェックします — あなたのスキル'の 構造、 説明、 トリガー 条件が 実際に Claude Code'のルーティングロジックで機能するかどうかを確認します。** それはスキルタイプの違いを理解し、コンテキストに応じた処方を生成し、ロールバックで問題を自動修正します。markdownlintは壊れた見出しをキャッチします。pulserは、あなたの説明が信頼性を持ってルーティングするにはあまりにも一般的であることを伝え、書き直します。

## 自分で試してみてください

1. Claude Codeスキルがある任意のディレクトリで `npx pulser-cli` を実行します
2. 出力を読みます — まずコア層の失敗を修正します
3. `npx pulser-cli --fix` を実行して提案された修正を確認します
4. 修正を受け入れ、Claudeがあなたのスキルにより信頼性を持ってルーティングすることを確認します
5. 継続的な強制を希望する場合はプレコミットフックを追加します
6. 役に立った場合はリポジトリにスターを付けてください: [whynowlab/pulser](https://github.com/whynowlab/pulser)

## 次は何ですか？

もし あなたがClaude Codeのスキルを作成し、なぜClaudeが時々それらを無視するのか疑問に思ったことはありませんか — スキャンを実行してください。**私が分析した50以上のスキルファイルで最も一般的な失敗は、Claudeが信頼性を持ってルーティングできないほど一般的すぎる説明フィールドです。** あなたのスキルが同じ問題を抱えているかどうかを確認するのに4秒かかります。

Claude Codeでスキルの信頼性の問題に直面したことはありますか？どのような失敗パターンを見ましたか？コメントを残してください — 私は実際の失敗モードから次のルールセットを構築しています。仮定のものではなく、実際のものです。

---

*私は開発者で、AI駆動のインフラツールを構築しています。pulserは私自身のClaude Codeスキルファイルのデバッグスクリプトとして始まり、現在では初期採用者のセットアップで200以上のスキルファイルを診断したオープンソースCLIに成長しました。私は開発者ツールの構築と、それらをより良くするためのエンジニアリングのミスについて書いています。*