Agent Skill Use

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

Triggers

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: カテゴリの選択

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

| Trigger | Examples |
|---------|----------|
| [Category] | "[EN]", "[JP]" |

---

## 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 | Purpose |
|------|---------|
| `github.issues.create` | Issue作成 |
| `github.prs.review` | PRレビュー |

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

| Skill | Description | Triggers |
|-------|-------------|----------|
| skill-1 | Brief desc | /cmd, "phrase" |
| skill-2 | Brief desc | /cmd, "phrase" |

## 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削減の確認

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

Forbidden

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 – スキルインデックス