カスタムエージェントとスキル
専門ワークフロー用の .md ベース拡張機能の構築方法。
学ぶこと
Claude Code は固定されたプロダクトではありません。拡張可能なプラットフォームです。特定のディレクトリにMarkdownファイルを配置するだけで、まったく新しい機能を追加できます --- スラッシュコマンド、専門レビュアー、自動化ワークフロー、ドメイン特化アシスタント。
このセッションを終えると、以下を理解できるようになります：
- スキルとエージェントの違い
- スキル（ユーザー起動）とエージェント（AI起動）の書き方
- 両方の設計パターン
- 安全性のためのツール制限
- 呼び出しから実行までのライフサイクル
課題
すべてのチームにはワークフローがあります。デプロイ手順、レビューチェックリスト、テストプロトコル。この知識は通常、2つの場所に存在します：誰も読まないドキュメントと、一人の頭の中です。
"How do we deploy?" → Ask Sarah
"What's our PR checklist?" → It's in the wiki... somewhere
"Database migrations?" → Dave wrote a script, check his home dirもしこの知識がAI実行可能な指示だったら？ 単なるドキュメントではなく、AIが毎回ステップバイステップで従う指示だったらどうでしょうか？
仕組み
スキル vs エージェント
┌──────────────────────────────────────────────────────┐
│ Skills (User-invoked) Agents (AI-invoked) │
│ │
│ Triggered by slash command Triggered by AI via │
│ /deploy, /review Agent tool spawn │
│ │
│ Runs in main context Runs in child context │
│ (instructions injected) (isolated subagent) │
│ │
│ Location: Location: │
│ .claude/skills/name/SKILL.md .claude/agents/x.md │
└──────────────────────────────────────────────────────┘| 側面 | スキル | エージェント |
|---|---|---|
| トリガー | ユーザー（/skill-name） | AI（サブエージェントのスポーン） |
| コンテキスト | メイン会話に注入 | 分離された子コンテキスト |
| 目的 | ステップバイステップのワークフロー | 専門的な役割（レビュアー、探索者） |
| 配置場所 | .claude/skills/name/SKILL.md | .claude/agents/name.md |
スキルの構造
スキルはワークフロー指示を含むMarkdownドキュメントです：
# File: .claude/skills/deploy/SKILL.md
# Deploy Skill
1. Run `git status` to check for uncommitted changes
2. Run the full test suite with `npm test`
3. If tests fail, stop and report the failures
4. Run `npm run build` and verify no errors
5. Show the user: test results, build size, files changed
6. Ask: "Ready to deploy? [yes/no]"
7. Only if confirmed: run `git push origin main`
8. Report deployment status
## Rules
- NEVER push without user confirmation
- If any step fails, stop and reportユーザーが /deploy と入力すると、Claude Code はマッチするスキルを見つけ、その内容を注入し、指示に従います。
エージェントの構造
エージェントは、AIがサブエージェントとしてスポーンできる専門的な役割を定義します：
# File: .claude/agents/security-reviewer.md
# Security Reviewer
Review code for security vulnerabilities. Be thorough
but avoid false positives.
## Checklist
- SQL injection: raw queries with user input
- XSS: unescaped output in templates
- Auth bypass: missing middleware on protected routes
- Secrets: hardcoded API keys, passwords, tokens
- Path traversal: unsanitized file paths
## Output Format
For each finding: file, line, severity, issue, fix.
If clean: "No security issues found."
## Tools: Read, Glob, Grep onlyAIは必要に応じてこれをスポーンします：
{
"type": "tool_use",
"name": "Agent",
"input": {
"agent": "security-reviewer",
"prompt": "Review changes in src/api/ for security issues"
}
}スキルのライフサイクル
┌──────────────────────────────────────────────────────┐
│ 1. User types /deploy │
│ ▼ │
│ 2. Claude Code scans .claude/skills/ for match │
│ ▼ │
│ 3. Found: .claude/skills/deploy/SKILL.md │
│ ▼ │
│ 4. Skill body injected into conversation context │
│ ▼ │
│ 5. AI reads instructions, follows step by step │
│ ▼ │
│ 6. Workflow completes (or user interrupts) │
└──────────────────────────────────────────────────────┘スキル設計パターン
ステップバイステップワークフロー — 条件分岐付きの番号付きシーケンス：
1. Check preconditions
2. Gather information
3. Present plan to user
4. Execute with safety checks
5. Verify results
6. Report summaryデシジョンツリー — プロジェクトタイプに基づく分岐：
Check the project type:
- If `package.json` exists → Node.js
- If `tsconfig.json` → use `npx tsc --noEmit`
- Else → use `node --check`
- If `requirements.txt` exists → Python
- Use `python -m py_compile`
- If `Cargo.toml` exists → Rust
- Use `cargo check`テンプレートベース出力 — 構造化されたコンテンツ生成：
Generate a changelog using this format:
### [version] - YYYY-MM-DD
#### Added / Changed / Fixed
Fill by analyzing git commits since the last tag.ツール制限
ツールの制限は最小権限の原則に従います。レビュアーはコードを編集すべきではありません。探索者はコマンドを実行すべきではありません。
## Tools
Allowed: Read, Glob, Grep
Not allowed: Edit, Write, Bash, AgentAIがこのエージェントをスポーンすると、リストされたツールのみがアクセス可能になります。これにより、セキュリティレビュアーが発見した問題を誤って「修正」してしまうことを防ぎます。
重要なポイント
カスタムエージェントとスキルは、チームのワークフロー知識をエンコードします。 暗黙知を反復可能で一貫したAIの振る舞いに変換します。
平凡な Claude Code セットアップと強力なセットアップの違いは、モデルではなく、スキルとエージェントの質にあります。よく書かれたデプロイスキルは、すべてのデプロイが同じ安全チェックに従うことを意味します。よく書かれたセキュリティレビュアーは、すべてのPRが同じ厳密さで審査されることを意味します。
これは「Infrastructure as Code」をAIワークフローに適用したものです：Workflows as Markdown。 コンパイル不要、フレームワーク不要、デプロイメント不要。ファイルを配置するだけで、機能が追加されます。
ハンズオン
セキュリティエージェントをスポーンするレビュースキルを構築します：
レビュースキル（.claude/skills/review/SKILL.md）
# Code Review
1. Run `git diff main...HEAD --stat` to see changed files
2. For each changed file, read the diff and check for:
- Missing error handling
- Hardcoded values that should be config
- Functions longer than 50 lines
- Console.log left in
3. Spawn the security-reviewer agent on changed files
4. Compile findings:
### Summary
[1-2 sentence overview]
### Findings
| File | Line | Severity | Issue |
### Security Review
[Output from security-reviewer agent]
### Recommendation
[Approve / Request Changes]セキュリティエージェント（.claude/agents/security-reviewer.md）
# Security Reviewer
Check for: SQL injection, XSS, hardcoded secrets,
missing auth middleware, input validation gaps.
Output: file, line, severity, fix for each finding.
If clean: "No security issues found."
Tools: Read, Glob, Grep/review と入力すると、AIはスキルに従い、セキュリティエージェントをスポーンし、構造化されたレポートを生成します。誰が実行しても、すべてのレビューが一貫しています。
変更点まとめ
| 拡張機能なし | カスタムエージェントとスキルあり |
|---|---|
| ワークフローがドキュメントにある | ワークフローがAI実行可能 |
| 一貫性が実行者に依存 | 毎回同じステップ |
| 新メンバーにトレーニングが必要 | スキルがトレーニングをエンコード |
| レビューがレビュアーによって異なる | エージェントが同じチェックリストを適用 |
| 機能追加にコードが必要 | 機能追加にMarkdownファイルが必要 |
次のセッション
セッション24ですべてをまとめます。本番パターン --- 可観測性、CI/CD統合、コスト管理、そして組織全体でAIアシスト開発をスケーリングするための成熟度モデルを学びます。