Agent Skill Use

Version: 1.0.0 Purpose: ベストプラクティスに基づくエージェントスキルの作成・管理

Triggers

Trigger Examples

Skill Creation "create agent skill", "スキル作成", "new skill"

Context Optimization "optimize context", "コンテキスト最適化"

Multi-Agent Design "design multi-agent", "マルチエージェント設計"

Best Practices "agent best practices", "ベストプラクティス"

Reference Document

.claude/docs/AGENT_BEST_PRACTICES.md

このスキルは上記ドキュメントのパターンを実装します。

Core Concepts

1. 三層アーキテクチャ

┌──────────────┬─────────────────┬─────────────────┬─────────────────┐ │ │ MCP │ Skills │ Subagents │ ├──────────────┼─────────────────┼─────────────────┼─────────────────┤ │ Primary Role │ External │ Task │ Context │ │ │ Connection │ Specialization │ Isolation │ ├──────────────┼─────────────────┼─────────────────┼─────────────────┤ │ Context │ High (all tools │ Low (metadata │ Separate │ │ Impact │ loaded) │ first) │ window │ ├──────────────┼─────────────────┼─────────────────┼─────────────────┤ │ Best For │ API calls, │ Workflows, │ Parallel tasks, │ │ │ data access │ procedures │ isolation │ └──────────────┴─────────────────┴─────────────────┴─────────────────┘

2. Progressive Disclosure

Layer 1: Index Only (~500 tokens) ← Always loaded ↓ Layer 2: Skill Metadata (~1,000) ← On demand ↓ Layer 3: Full Content (~5,000) ← When activated

Workflow: Skill Creation

Phase 1: 要件定義

Step 1.1: スキルの目的を明確化

質問リスト:

1. このスキルは何を達成しますか？
2. どのようなトリガーで起動しますか？
3. 必要な入力は何ですか？
4. 期待する出力は何ですか？
5. どのツールが必要ですか？

Step 1.2: カテゴリの選択

Category Use Case

Task Automation 繰り返しタスクの自動化

Code Quality レビュー・テスト・リファクタ

DevOps デプロイ・監視・インフラ

Content ドキュメント・コンテンツ生成

Integration 外部サービス連携

Phase 2: 構造設計

Step 2.1: ディレクトリ作成

mkdir -p .claude/skills/[skill-name]/resources mkdir -p .claude/skills/[skill-name]/scripts

Step 2.2: 必須ファイル構成

.claude/skills/[skill-name]/ ├── SKILL.md # Required: メイン定義 ├── resources/ # Optional: 参照ドキュメント │ ├── templates.md # テンプレート集 │ └── examples.md # 使用例 └── scripts/ # Optional: 実行スクリプト └── helper.sh # ヘルパースクリプト

Phase 3: SKILL.md作成

Step 3.1: Frontmatter

name: "kebab-case-name" # Required description: "[Action] [Object]. Use when [trigger]." # Required allowed-tools: Bash, Read, Write # Required version: "1.0.0" # Optional triggers: # Optional (for documentation)

• "/command"
• "natural language trigger" dependencies: # Optional
• "other-skill" mcp_tools: # Optional (wrapped MCP tools)
• "github.issues"

Step 3.2: 構造テンプレート

[Skill Title]

Version: X.Y.Z Purpose: [One-line purpose]

Triggers

Workflow

Phase 1: [Title]

Step 1.1: [Substep]

[Instructions]

Best Practices

✅ GOOD: [Pattern] ❌ BAD: [Anti-pattern]

Checklist

• [Item 1]
• [Item 2]

Phase 4: MCP Tool Wrapping

Step 4.1: ツールをスキル内にラップ

<!-- SKILL.md内 -->

Integrated Tools

This skill wraps the following MCP tools:

Tool Usage

Tool definitions are loaded only when this skill is activated, following progressive disclosure pattern.

Step 4.2: Tool Index (Full Definitionではなく)

<!-- resources/tool-index.md -->

Tool Index

Available Tools

• tool.name - Brief description
• tool.name2 - Brief description

Full definitions loaded on demand.

Phase 5: Subagent統合（必要な場合）

Step 5.1: Subagent使用判断

Task received │ ▼ ┌─────────────────┐ │ Parallel tasks │──Yes──► Use Subagent │ (>3 independent)│ └────────┬────────┘ │ No ▼ ┌─────────────────┐ │ Security │──Yes──► Use Subagent │ isolation needed│ └────────┬────────┘ │ No ▼ ┌─────────────────┐ │ Long-running │──Yes──► Use Subagent │ background task │ └────────┬────────┘ │ No ▼ Use Skills instead (default)

Step 5.2: Subagent Spawn定義

agents/[agent-name]/AGENT.md frontmatter

name: "parallel-executor" type: "subagent" spawn_conditions:

• "independent_tasks > 3"
• "explicit_parallel_request" context_inheritance: "minimal"

Workflow: Context Optimization

Step 1: 現状分析

スキル数とサイズを確認

find .claude/skills -name "SKILL.md" -exec wc -l {} ;

MCPツール数を確認

grep -r "mcp_tools" .claude/skills/

Step 2: Index作成

<!-- .claude/overview.md -->

version: "1.0" last_updated: "YYYY-MM-DD"

Project Agent Configuration

Available Skills

Loading Rules

1. Always load: This overview only
2. On skill trigger: Load SKILL.md metadata
3. On execution: Load full skill content

Step 3: Token削減の確認

Metric Target

Base context <15,000 tokens

Skill load time <500ms

Token reduction

30%

Workflow: Multi-Agent Design

Team Structure

┌─────────────┐ │ Coordinator │ │ (Lead) │ └──────┬──────┘ │ ┌──────┴──────┬───────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Planning │ │ Execution│ │ Review │ │ Team │ │ Team │ │ Team │ └──────────┘ └──────────┘ └──────────┘

A2A Message Format

{ "message_id": "uuid-v4", "from_agent": "coordinator", "to_agent": "execution-team", "intent": "execute_task", "payload": { "task_id": "task-123", "description": "Task description", "priority": "high" } }

Naming Rules

Required

Rule Example

Kebab-case my-skill

Lowercase code-reviewer

Descriptive test-generator

Forbidden

Word Reason

claude

Trademark

anthropic

Company name

mcp

Protocol name

Validation Checklist

Structure

• Directory at .claude/skills/[name]/

• SKILL.md has valid frontmatter

• Name is kebab-case, no forbidden words

Content

• Description has action + trigger

• Triggers cover EN and JP

• Steps are clear and actionable

• Best practices documented

Integration

• MCP tools wrapped (not loaded directly)

• Subagent criteria defined (if needed)

• Index updated in overview.md

Quick Reference

Create New Skill

1. Create directory

mkdir -p .claude/skills/my-skill/resources

2. Create SKILL.md

cat > .claude/skills/my-skill/SKILL.md << 'EOF'

name: my-skill description: Does X. Use when Y. allowed-tools: Bash, Read, Write

My Skill

Version: 1.0.0 Purpose: [Purpose]

Workflow

Step 1: [Title]

[Instructions] EOF

3. Update overview

echo "| my-skill | Does X | /my, "do x" |" >> .claude/overview.md

Validate Skill

Check frontmatter

head -n 6 .claude/skills/my-skill/SKILL.md

Test trigger (in Claude)

"do x" → Skill should activate

Related Documents

• .claude/docs/AGENT_BEST_PRACTICES.md

• 完全なベストプラクティス

• .claude/skills/skill-creator/SKILL.md

• 基本スキル作成

• .claude/skills/README.md

• スキルインデックス