SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsagent-skill-use

agent-skill-use

Agents & models

View repository

Updated 10-16 08:45

About this skill

Agent Skill Use

Version: 1.0.0 Purpose: Creating and managing agent skills based on best practices

Triggers

Trigger Examples
Skill Creation "create agent skill", "skill creation", "new skill"
Context Optimization "optimize context", "context optimization"
Multi-Agent Design "design multi-agent", "multi-agent design"
Best Practices "agent best practices", "best practices"

Reference Document

.claude/docs/AGENT_BEST_PRACTICES.md

This skill implements the patterns in the above document.

Core Concepts

1. Three-layer architecture

┌──────────────┬─────────────────┬─────────────────┬─────────────────┐
│              │      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: Requirements definition

Step 1.1: Clarify the purpose of the skill

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

Step 1.2: Selecting a category

Category Use Case
Task Automation Automation of repetitive tasks
Code Quality Review, testing, refactoring
DevOps Deployment, monitoring, infrastructure
Content Documentation and content generation
Integration External service integration

Phase 2: Structural design

Step 2.1: Creating directories

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

Step 2.2: Required file structure

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

Phase 3: Creating 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: Structure template

# [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: Wrapping tools within the skill

<!-- 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 (instead of 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 integration (when necessary)

Step 5.1: Deciding whether to use a 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 definition

# 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: Current state analysis

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

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

Step 2: Creating the 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: Verifying token reduction

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 - Complete best practices
  • .claude/skills/skill-creator/SKILL.md - Basic skill creation
  • .claude/skills/README.md - Skill index