home / skills / shunsukehayashi / miyabi / agent-skill-use

agent-skill-use skill

safe

This skill helps you create and manage AI agent skills following best practices for multi-agent design and progressive disclosure.

npx playbooks add skill shunsukehayashi/miyabi --skill agent-skill-use

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

10.2 KB

---
name: agent-skill-use
description: Create and manage AI agent skills following best practices. Use when creating new skills, optimizing context, designing multi-agent systems, or implementing progressive disclosure patterns.
allowed-tools: Bash, Read, Write, Grep, Glob, Edit
---

# 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: スキルの目的を明確化

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

#### Step 1.2: カテゴリの選択

| Category | Use Case |
|----------|----------|
| **Task Automation** | 繰り返しタスクの自動化 |
| **Code Quality** | レビュー・テスト・リファクタ |
| **DevOps** | デプロイ・監視・インフラ |
| **Content** | ドキュメント・コンテンツ生成 |
| **Integration** | 外部サービス連携 |

---

### Phase 2: 構造設計

#### Step 2.1: ディレクトリ作成

```bash
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

```yaml
---
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: 構造テンプレート

```markdown
# [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: ツールをスキル内にラップ

```markdown
<!-- 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ではなく)

```markdown
<!-- 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定義

```yaml
# 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: 現状分析

```bash
# スキル数とサイズを確認
find .claude/skills -name "SKILL.md" -exec wc -l {} \;

# MCPツール数を確認
grep -r "mcp_tools" .claude/skills/
```

### Step 2: Index作成

```markdown
<!-- .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削減の確認

| 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

```json
{
  "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

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

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

Overview

This skill helps you create and manage AI agent skills following proven patterns and operational best practices. It provides a three-layer architecture and progressive disclosure for efficient context management. Use it to design subagents, wrap external tools, and keep token usage and load times under control.

How this skill works

The skill defines a lightweight index-first loading strategy: an index always loaded, metadata loaded on trigger, and full content loaded only on activation. It prescribes a three-layer architecture (connector, skill, subagent) that separates external connections, task logic, and isolated execution contexts. It also supplies checklists and spawn rules for when to use subagents versus in-skill workflows.

When to use it

Creating a new agent skill that needs clear purpose, inputs, and triggers
Optimizing context size and token usage across many skills
Designing multi-agent systems with coordinator and worker roles
Implementing progressive disclosure to reduce load time and costs
Deciding whether tasks require parallel, isolated subagents

Best practices

Adopt the three-layer architecture: connector (MCP), skills, subagents for isolation
Use progressive disclosure: index → metadata → full content to save tokens
Wrap external tools behind skill interfaces; load full tool definitions on demand
Define clear spawn conditions for subagents: parallelism, isolation, long-running work
Name skills in kebab-case, lowercase, and avoid forbidden trademark words
Keep base context under target token budgets and measure load times

Example use cases

Automating a CI workflow: skill handles orchestration, subagents run parallel test suites
Creating a code-quality skill: wraps linters and PR reviewers and loads tools on activation
Building an integration skill: minimal index loaded, full API bindings loaded only when used
Designing a multi-agent review pipeline: coordinator issues tasks, review team agents process items
Progressively disclosing documentation for large content generation tasks to reduce token costs

FAQ

How do I decide between a skill and a subagent?

Use subagents for >3 independent parallel tasks, strong security isolation, or long-running background jobs; otherwise implement logic as a skill.

What should I include in the skill manifest?

Include name (kebab-case), concise description with action and trigger, allowed tools, and any wrapped tool references; keep heavy definitions out of the always-loaded index.