skill-builder

スキルビルダー

このライブラリに含めるエージェントスキルの作成方法です。この標準に厳密に従ってください。dogfooded-skills のすべてのスキルは、マージ前にこの標準に照らしてレビューされています。

スキルとは？

スキルとは、.claude/skills/<skill-name>/SKILL.md にある Markdown ファイルです。スキルの呼び出しによって起動されたとき、またはプロジェクトの指示ファイルで参照されたときに、エージェントのコンテキストに読み込まれます。スキルはプロンプトではなく、実行手順書です。具体的なコマンド、判断表、明示的な注意点によって、エージェントを特定領域のエキスパートにします。

スキルは、次のものではありません。

• ツールの機能を説明する README
• ユーザーが読むための例の集まり
• 設定ファイル
• 検討事項を曖昧に列挙したもの

スキルとは、次のものです。

• エージェントが読むのではなく、実行する手順
• 疑似コードではなく、実際のフラグを指定した実際のコマンド
• 1つの機能に関する信頼できる唯一の情報源

ファイル構成

skills/
  <skill-name>/
    SKILL.md          ← required: the skill itself
    <support-files>   ← optional: scripts, templates, reference data

スキル名は小文字のケバブケースにします。曖昧さがない範囲で最短の名前を使います。dependency-update-runner ではなく、deps-runner とします。

-runner の接尾辞は、オペレーター側のディスパッチャーを表します。 *-runner という名前のスキルは開発環境の外で動作し、開発環境を操作します。ワーカーを起動または指定し、プロンプトを送り、ポーリングし、検証して報告します。エンジンをインラインで実行することはありません。エンジン側のスキルには接尾辞を付けず、ゲートウェイにアクセスできない任意のチェックアウト内で動作する必要があります。この接尾辞は pylot skills list --kind runner のフィルター仕様の一部です。そのため、ほかの用途には使わないでください。

フロントマター

すべての SKILL.md は YAML フロントマターから始める必要があります。

---
name: skill-name
description: One-line summary — used by the agent to decide relevance. Be specific.
allowed-tools: Read, Write, Bash, Glob, Grep  # optional — restrict tool use
---

フィールドのルール

name — ディレクトリ名と一致させます。スペースや大文字は使えません。

description — 平易な英語で1行にします。エージェントはこれを読み、スキルを呼び出すかどうかを判断します。悪い例：「環境を管理する」。良い例：「CI／エージェントのワークロード向けに、Gitpod クラウド環境を確保、起動、SSH 接続、解放する。」

requires_worker_skills — runner のみ：ワーカーが必要とするエンジンスキルを、フラットなインラインリストで指定します（requires_worker_skills: [ce-debug]。ブロック形式の YAML リストは読み込まれません）。Pylot は各スキルのカタログ上のオリジンを解決し、ミッションワーカーの起動時にユーザースコープでインストールします。インストールできない場合、起動は失敗します。指定する各エンジンは、owner/repo のオリジンとともに組織のスキルカタログに登録されている必要があります。

allowed-tools — このスキルが使用できるツールのホワイトリストです。指定しない場合は、すべてのツールが許可されます。スキルの使用を制限する場合（例：読み取り専用の監査スキル）に設定します。

セクション構成

スキルには、次のセクションをこの順序で記載する必要があります。

1. 1行の目的（H1）

タイトルはスキル名にします。最初の段落（見出しなし）は、目的を1文で記述します。例：

# deps-runner

Run dependency update PRs through a verification pipeline — checkout, build, test, classify risk, auto-merge or flag.

2. 使用する場面（任意ですが推奨）

呼び出しのきっかけを箇条書きにします。別の方法ではなく、このスキルをエージェントが呼び出すべきなのはどのような場合ですか？

## When to Use

- Dependabot or Renovate PRs that need automated verification
- Batch processing multiple dep updates for the same repo
- When you need a risk classification before merging

3. 前提条件

スキルの実行前に満たされている必要がある条件をすべて記載します。検証コマンドも含めてください。

## Prerequisites

```bash
gitpod version && gitpod whoami  # Gitpod CLI authenticated
gh auth status                    # GitHub CLI authenticated

4. 主なワークフロー

スキルの中核です。番号付きの手順で記述し、判断ポイントを明確に示します。

ルール：

• 順番に行う操作には番号付きの手順を使います
• エラーが起きやすい手順には > **Warning:** を使います
• 複数行の bash は、bash を指定したフェンス付きコードブロックで囲みます
• 検証に重要な場合は、期待される出力を示します
• 判断ポイントには表または if/else の説明を使います。「状況に応じて」のような曖昧な表現は避けてください

例：

## Workflow

1. **List environments**
   ```bash
   gitpod environment list --timeout 60s

リポジトリ URL でフィルターします。このリポジトリの実行中／停止中の環境数を数えます。

2. プールの上限を確認する — 数が 3 以上（issue の場合）または 2 以上（deps の場合）なら中止します

3. 停止中の環境を確保する（新規作成より再利用を優先します）

   gitpod environment start {env-id} --set-as-context --dont-wait
   

   確保する前に、アクティブな pilot がないか確認してください：

   gitpod environment ssh {env-id} -- "pgrep -x claude || echo NO_PILOT"
   

   claude プロセスが存在する場合、このポッドは使用中です。別のものを選んでください。

### 5. Decision Tables

Use tables whenever there are multiple paths or risk tiers.

```markdown
## Risk Classification

| Condition | Risk | Action |
|-----------|------|--------|
| Patch update, build passes, tests pass | Low | Auto-merge with [skip ci] |
| Minor update, build passes | Medium | Flag for review |
| Major update or build fail | High | Block — manual review required |

6. エラー処理

明示的な失敗条件と、その場合の対処方法を記載します。網羅する必要はありません。自明でないものだけを記載してください。

## Error Handling

**`pgrep -x claude` returns a PID** — pod is mid-mission. Do not claim. Pick a different env.

**Build fails on `bundle install`** — check Ruby version. Lexgo requires Ruby 3.2.x. Run `ruby -v` inside the env.

**`gitpod environment ssh` times out** — env may still be starting. Poll with `gitpod environment get {env-id}` and retry after 15s.

7. 重要なルール（任意）

絶対に守らなければならないルールを箇条書きで記載します。違反によってデータの損失、リソースの漏えい、セキュリティ上の問題が発生する場合に使用します。

## Critical Rules

- **Always release envs after use** — stopped envs cost nothing; leaked running envs burn credits
- **Never skip decontamination** — a stopped pod resumes with stale git state
- **One agent process per env** — two agents share a git working directory and corrupt each other

説明のルール

description: フィールドはルーティングのシグナルであり、オペレーターがこのスキルをいつ使うかを決定します。必ず、実行可能なトリガーから始めてください。

良い例	悪い例
「リポジトリの deps パイプラインを実行するときに使用します。」	「deps-runner の 6 段階の逐次 ICM 手順。」
「Fly.io へのデプロイ、または flyctl の設定に使用します。」	「Fly.io プラットフォームにアプリケーションをデプロイします。」
「Dependabot/Snyk のアラートをトリアージするときに使用します。」	「セキュリティアラートのトリアージフレームワーク。」

セルフチェック： 説明から「このスキルをいつ選ぶべきか」が分かりますか？ 使用する「タイミング」ではなく、スキルの「仕組み」を説明している場合は、書き直してください。

使用できるトリガー形式：「Use when ...」「Use to ...」「Use as ...」（インポート専用スキルの場合）。段階数や並列処理などの仕組みに関する説明は、description ではなくスキル本文に記載してください。

品質チェックリスト

スキルを提出する前に、すべての項目を確認してください。

• Frontmatter が完全で、有効な YAML である
• description が類似スキルと区別できるほど具体的である
• スキル内のすべてのコマンドが、実際のターミナルセッションからコピー＆ペーストされている
• よくある 3 つの失敗モードに対するエラー処理が記載されている
• 疑似コードがない — すべての手順に実際に実行可能なコマンドがある
• 判断が必要な箇所に表または明示的な条件があり、「場合によります」になっていない
• ユーザー への指示がない — すべての文章がエージェントに向けられている
• 実際のワークロードに対して、少なくとも 5 回スキルを実行している

よくあるアンチパターン

曖昧すぎる

# Bad
3. Run the appropriate command to start the environment.

# Good
3. Start the environment:
   ```bash
   gitpod environment start {env-id} --set-as-context --dont-wait

### Instructing the user instead of the agent

```markdown
# Bad
The user should verify that the environment is running before proceeding.

# Good
Verify the environment is running:
```bash
gitpod environment get {env-id} --timeout 15s | grep -i "running"

### Missing the "when not to use" case

A skill that can be over-applied is dangerous. If there are situations where the skill should NOT be invoked, say so explicitly.

```markdown
## When NOT to Use

- Major version upgrades with breaking changes — these need manual review
- PRs that touch `schema.rb` or database migrations

注意点を文章に埋もれさせる

注意点は視覚的に目立つようにしてください。> **Warning:**、太字、または専用のセクションを使用します。段落 3 に埋もれた注意点は見落とされます。

テンプレート

出発点として、これをコピーしてください。

---
name: your-skill
description: One specific sentence about what this skill does and for what context.
allowed-tools: Read, Write, Bash, Glob, Grep
---

# Your Skill

One sentence: what this skill does and why it exists.

## When to Use

- Trigger A
- Trigger B

## Prerequisites

```bash
# verification commands

ワークフロー

1. ステップ 1

   command here
   

2. ステップ 2 — 判断ポイント

   条件	アクション
   ケース A	X を実行
   ケース B	Y を実行

エラー処理

よくある失敗 — 対処方法。

重要なルール

• ルール 1
• ルール 2