Back to Details

skill-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Integration Skill

Skill集成Skill

Standardized patterns for how agents discover, reference, and use skills effectively in Claude Code 2.0+.
在Claude Code 2.0+中，Agent有效发现、引用和使用Skill的标准化模式。

When This Activates

适用场景

  • Working with agent prompts or skill references
  • Implementing new agents or skills
  • Understanding skill architecture
  • Optimizing context usage
  • Keywords: "skill", "progressive disclosure", "skill discovery", "agent integration"
  • 处理Agent提示词或Skill引用时
  • 实现新的Agent或Skill时
  • 理解Skill架构时
  • 优化上下文使用时
  • 关键词："skill"、"progressive disclosure"、"skill discovery"、"agent integration"

Overview

概述

The skill-integration skill provides standardized patterns for:
  • Skill discovery: How agents find relevant skills based on task keywords
  • Progressive disclosure: Loading skill content on-demand to prevent context bloat
  • Skill composition: Combining multiple skills for complex tasks
  • Skill reference format: Consistent way agents reference skills in prompts
Skill集成Skill提供以下标准化模式：
  • Skill发现：Agent如何根据任务关键词找到相关Skill
  • 渐进式披露（Progressive Disclosure）：按需加载Skill内容，避免上下文冗余
  • Skill组合：为复杂任务组合多个Skill
  • Skill引用格式：Agent在提示词中引用Skill的统一方式

Progressive Disclosure Architecture

渐进式披露架构

What It Is

定义

Progressive disclosure is a design pattern where:
  1. Metadata stays in context - Skill names, descriptions, keywords (~50 tokens)
  2. Full content loads on-demand - Detailed guidance only when needed (~5,000-15,000 tokens)
  3. Context stays efficient - Support 50-100+ skills without bloat
渐进式披露是一种设计模式，其中：
  1. 元数据保留在上下文中 - Skill名称、描述、关键词（约50个token）
  2. 完整内容按需加载 - 仅在需要时加载详细指南（约5000-15000个token）
  3. 上下文保持高效 - 支持50-100+个Skill而不产生冗余

Why It Matters

重要性

Without progressive disclosure:
  • 20 skills × 500 tokens each = 10,000 tokens in context
  • Context bloated before agent even starts work
  • Can't scale beyond 20-30 skills
With progressive disclosure:
  • 100 skills × 50 tokens each = 5,000 tokens in context
  • Full skill content only loads when relevant
  • Scales to 100+ skills without performance issues
无渐进式披露时：
  • 20个Skill × 每个500token = 上下文占用10000token
  • Agent开始工作前上下文就已冗余
  • 无法扩展到20-30个Skill以上
使用渐进式披露时：
  • 100个Skill × 每个50token = 上下文占用5000token
  • 仅在相关时加载完整Skill内容
  • 可扩展到100+个Skill且无性能问题

How It Works

工作原理

┌─────────────────────────────────────────────────────────┐
│                   Agent Context                          │
│                                                          │
│  Agent Prompt: ~500 tokens                              │
│  Skill Metadata: 20 skills × 50 tokens = 1,000 tokens  │
│  Task Description: ~200 tokens                          │
│                                                          │
│  Total: ~1,700 tokens (efficient!)                      │
└─────────────────────────────────────────────────────────┘
                          │
                          │ Agent encounters keyword
                          │ matching skill
                          ↓
┌─────────────────────────────────────────────────────────┐
│              Skill Content Loads On-Demand               │
│                                                          │
│  Skill Full Content: ~5,000 tokens                      │
│  Loaded only when needed                                │
│                                                          │
│  Total context: 1,700 + 5,000 = 6,700 tokens           │
│  Still efficient!                                        │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│                   Agent Context                          │
│                                                          │
│  Agent Prompt: ~500 tokens                              │
│  Skill Metadata: 20 skills × 50 tokens = 1,000 tokens  │
│  Task Description: ~200 tokens                          │
│                                                          │
│  Total: ~1,700 tokens (efficient!)                      │
└─────────────────────────────────────────────────────────┘
                          │
                          │ Agent encounters keyword
                          │ matching skill
                          ↓
┌─────────────────────────────────────────────────────────┐
│              Skill Content Loads On-Demand               │
│                                                          │
│  Skill Full Content: ~5,000 tokens                      │
│  Loaded only when needed                                │
│                                                          │
│  Total context: 1,700 + 5,000 = 6,700 tokens           │
│  Still efficient!                                        │
└─────────────────────────────────────────────────────────┘

Skill Discovery Mechanism

Skill发现机制

Keyword-Based Activation

基于关键词的激活

Skills auto-activate when task keywords match skill keywords:
Example: testing-guide skill
yaml
---
name: testing-guide
keywords: test, testing, pytest, tdd, coverage, fixture
auto_activate: false
---
Task triggers skill:
  • "Write tests for user authentication" → matches "test", "testing"
  • "Add pytest fixtures for database" → matches "pytest", "fixture"
  • "Improve test coverage to 90%" → matches "testing", "coverage"
当任务关键词与Skill关键词匹配时，Skill会自动激活：
示例：testing-guide skill
yaml
---
name: testing-guide
keywords: test, testing, pytest, tdd, coverage, fixture
auto_activate: false
---
触发Skill的任务：
  • "为用户认证编写测试" → 匹配"test"、"testing"
  • "为数据库添加pytest夹具" → 匹配"pytest"、"fixture"
  • "将测试覆盖率提升至90%" → 匹配"testing"、"coverage"

Manual Skill Reference

手动引用Skill

Agents can explicitly reference skills in their prompts:
markdown
undefined
Agent可以在提示词中显式引用Skill：
markdown
undefined

Relevant Skills

相关Skill

You have access to these specialized skills:
  • testing-guide: Pytest patterns, TDD workflow, coverage strategies
  • python-standards: Code style, type hints, docstring conventions
  • security-patterns: Input validation, authentication, OWASP compliance

**Benefits:**
- Agent knows which skills are available for its domain
- Progressive disclosure still applies (metadata in context, content on-demand)
- Helps agent make better decisions about when to consult specialized knowledge
你可以使用以下专业Skill：
  • testing-guide：Pytest模式、TDD工作流、覆盖率策略
  • python-standards：代码风格、类型提示、文档字符串规范
  • security-patterns：输入验证、认证、OWASP合规性

**优势：**
- Agent了解其领域可用的Skill
- 仍适用渐进式披露（元数据在上下文，内容按需加载）
- 帮助Agent更好地决定何时参考专业知识

Skill Composition

Skill组合

Combining Multiple Skills

多Skill组合

Complex tasks often require multiple skills:
Example: Implementing authenticated API endpoint
markdown
Task: "Implement JWT authentication for user API endpoint"

Skills activated:
1. **api-design** - REST API patterns, endpoint structure
2. **security-patterns** - JWT validation, authentication best practices
3. **python-standards** - Code style, type hints
4. **testing-guide** - Security testing patterns
5. **python-standards** - Docstring and documentation standards

Progressive disclosure:
- All 5 skill metadata in context (~250 tokens)
- Full content loads only as needed (~20,000 tokens total)
- Agent accesses relevant sections progressively
复杂任务通常需要多个Skill：
示例：实现带认证的API端点
markdown
任务："为用户API端点实现JWT认证"

激活的Skill：
1. **api-design** - REST API模式、端点结构
2. **security-patterns** - JWT验证、认证最佳实践
3. **python-standards** - 代码风格、类型提示
4. **testing-guide** - 安全测试模式
5. **python-standards** - 文档字符串和文档标准

渐进式披露：
- 所有5个Skill的元数据在上下文中（约250token）
- 仅在需要时加载完整内容（总计约20000token）
- Agent逐步访问相关部分

Skill Layering

Skill分层

Skills can reference other skills:
markdown
undefined
Skill可以引用其他Skill：
markdown
undefined

Relevant Skills

相关Skill

  • testing-guide: Testing patterns (references python-standards for test code style)
  • security-patterns: Security best practices (references api-design for secure endpoints)
  • python-standards: Documentation standards (docstrings and code style)

**Benefits:**
- Natural skill hierarchy
- Agent discovers related skills automatically
- No need to list every transitive dependency
  • testing-guide：测试模式（参考python-standards获取测试代码风格）
  • security-patterns：安全最佳实践（参考api-design获取安全端点设计）
  • python-standards：文档标准（文档字符串和代码风格）

**优势：**
- 自然的Skill层级结构
- Agent自动发现相关Skill
- 无需列出所有传递依赖

Standardized Agent Skill References

标准化Agent Skill引用

Template Format

模板格式

Every agent should include a "Relevant Skills" section:
markdown
undefined
每个Agent都应包含"相关Skill"部分：
markdown
undefined

Relevant Skills

相关Skill

You have access to these specialized skills when [agent task]:
  • [skill-name]: [Brief description of what guidance this provides]
  • [skill-name]: [Brief description of what guidance this provides]
  • [skill-name]: [Brief description of what guidance this provides]
Note: Skills load automatically based on task keywords. Consult skills for detailed guidance on specific patterns.
undefined
当[Agent任务]时，你可以使用以下专业Skill：
  • [skill-name]：[该Skill提供的简要指南说明]
  • [skill-name]：[该Skill提供的简要指南说明]
  • [skill-name]：[该Skill提供的简要指南说明]
注意：Skill会根据任务关键词自动加载。如需特定模式的详细指南，请参考Skill。
undefined

Best Practices

最佳实践

✅ Do's:
  • List 3-7 most relevant skills for agent's domain
  • Use consistent skill names (match SKILL.md 
    name:
    field)
  • Keep descriptions concise (one line)
  • Add note about progressive disclosure
  • Trust skill discovery mechanism
❌ Don'ts:
  • List all 21 skills (redundant, bloats context)
  • Duplicate skill content in agent prompt
  • Provide detailed skill guidance inline
  • Override skill content with conflicting guidance
  • Assume skills are "just documentation"
✅ 建议：
  • 列出Agent领域内3-7个最相关的Skill
  • 使用统一的Skill名称（与SKILL.md中的
    name:
    字段匹配）
  • 描述保持简洁（一行）
  • 添加关于渐进式披露的说明
  • 信任Skill发现机制
❌ 禁忌：
  • 列出全部21个Skill（冗余，导致上下文膨胀）
  • 在Agent提示词中重复Skill内容
  • 内联提供详细的Skill指南
  • 用冲突的指南覆盖Skill内容
  • 认为Skill只是"文档"

Example: implementer Agent

示例：实现者Agent

markdown
undefined
markdown
undefined

Relevant Skills

相关Skill

You have access to these specialized skills when implementing features:
  • python-standards: Code style, type hints, docstring conventions
  • api-design: REST API patterns, error handling
  • database-design: Query optimization, schema patterns
  • testing-guide: Writing tests alongside implementation
  • security-patterns: Input validation, secure coding practices
  • observability: Logging, metrics, tracing
  • error-handling-patterns: Standardized error handling and recovery
Note: Skills load automatically based on task keywords. Consult skills for detailed guidance on specific patterns.

**Token impact:**
- Before: 500+ tokens of inline guidance
- After: 150 tokens referencing skills
- Savings: 350 tokens (70% reduction)
当实现功能时，你可以使用以下专业Skill：
  • python-standards：代码风格、类型提示、文档字符串规范
  • api-design：REST API模式、错误处理
  • database-design：查询优化、模式设计
  • testing-guide：边实现边编写测试
  • security-patterns：输入验证、安全编码实践
  • observability：日志、指标、追踪
  • error-handling-patterns：标准化错误处理与恢复
注意：Skill会根据任务关键词自动加载。如需特定模式的详细指南，请参考Skill。

**Token影响**：
- 之前：500+token的内联指南
- 之后：150token的Skill引用
- 节省：350token（减少70%）

Token Reduction Benefits

Token减少的优势

Per-Agent Savings

单Agent节省

Typical agent with verbose "Relevant Skills" section:
Before (verbose inline guidance):
markdown
undefined
带有冗长"相关Skill"部分的典型Agent：
之前（冗长内联指南）：
markdown
undefined

Relevant Skills

相关Skill

Testing Patterns

测试模式

  • Use pytest for all tests
  • Follow Arrange-Act-Assert pattern
  • Use fixtures for setup
  • Aim for 80%+ coverage
  • [... 300 more words ...]
  • 使用pytest进行所有测试
  • 遵循Arrange-Act-Assert模式
  • 使用夹具进行初始化
  • 目标覆盖率80%以上
  • [... 300余字 ...]

Code Style

代码风格

  • Use black for formatting
  • Add type hints to all functions
  • Write Google-style docstrings
  • [... 200 more words ...]
  • 使用black进行格式化
  • 为所有函数添加类型提示
  • 编写Google风格的文档字符串
  • [... 200余字 ...]

Security

安全

  • Validate all inputs
  • Use parameterized queries
  • [... 150 more words ...]

**Token count**: ~500 tokens

**After (skill references):**
```markdown
  • 验证所有输入
  • 使用参数化查询
  • [... 150余字 ...]

**Token数量**：~500token

**之后（Skill引用）：**
```markdown

Relevant Skills

相关Skill

You have access to these specialized skills when implementing features:
  • testing-guide: Pytest patterns, TDD workflow, coverage strategies
  • python-standards: Code style, type hints, docstring conventions
  • security-patterns: Input validation, secure coding practices
Note: Skills load automatically based on task keywords. Consult skills for detailed guidance.

**Token count**: ~150 tokens

**Savings**: 350 tokens per agent (70% reduction)
当实现功能时，你可以使用以下专业Skill：
  • testing-guide：Pytest模式、TDD工作流、覆盖率策略
  • python-standards：代码风格、类型提示、文档字符串规范
  • security-patterns：输入验证、安全编码实践
注意：Skill会根据任务关键词自动加载。如需特定模式的详细指南，请参考Skill。

**Token数量**：~150token

**节省**：每个Agent节省350token（减少70%）

Across All Agents

全Agent范围节省

  • 20 agents × 350 tokens saved = 7,000 tokens
  • Plus: Skills themselves deduplicate shared guidance
  • Result: 20-30% overall token reduction in agent prompts
  • 20个Agent × 节省350token = 7000token
  • 此外：Skill本身可复用共享指南，减少重复
  • 结果：Agent提示词整体Token减少20-30%

Scalability

可扩展性

With inline guidance (doesn't scale):
  • 20 agents × 500 tokens = 10,000 tokens
  • Can't add more specialized guidance without bloating prompts
  • Context budget limits agent capability
With skill references (scales infinitely):
  • 20 agents × 150 tokens = 3,000 tokens
  • Can add 100+ skills without impacting agent prompt size
  • Progressive disclosure ensures context efficiency
使用内联指南（无法扩展）：
  • 20个Agent × 500token = 10000token
  • 无法添加更多专业指南而不导致提示词膨胀
  • 上下文预算限制Agent能力
使用Skill引用（无限扩展）：
  • 20个Agent × 150token = 3000token
  • 可添加100+个Skill而不影响Agent提示词大小
  • 渐进式披露确保上下文高效

Real-World Examples

实际案例

Example 1: researcher Agent

案例1：研究员Agent

Before:
markdown
undefined
之前：
markdown
undefined

Relevant Skills

相关Skill

Research Patterns

研究模式

When researching, follow these best practices:
  • Start with official documentation
  • Check multiple sources for accuracy
  • Document sources with URLs
  • Identify common patterns across sources
  • Note breaking changes and deprecations
  • Verify information is current (check dates)
  • Look for code examples and real-world usage
  • [... 400 more words ...]

**Token count**: ~600 tokens

**After:**
```markdown
进行研究时，请遵循以下最佳实践：
  • 从官方文档开始
  • 检查多个来源以确保准确性
  • 记录来源URL
  • 识别跨来源的通用模式
  • 注意重大变更和弃用内容
  • 验证信息是否最新（检查日期）
  • 寻找代码示例和实际使用案例
  • [... 400余字 ...]

**Token数量**：~600token

**之后：**
```markdown

Relevant Skills

相关Skill

You have access to these specialized skills when researching:
  • python-standards: Documentation standards for research findings
Note: Skills load automatically based on task keywords.

**Token count**: ~100 tokens

**Savings**: 500 tokens (83% reduction)
当进行研究时，你可以使用以下专业Skill：
  • python-standards：研究成果的文档标准
注意：Skill会根据任务关键词自动加载。

**Token数量**：~100token

**节省**：500token（减少83%）

Example 2: planner Agent

案例2：规划者Agent

Before:
markdown
undefined
之前：
markdown
undefined

Relevant Skills

相关Skill

Architecture Patterns

架构模式

Follow these architectural patterns:
  • [... 300 words ...]
遵循以下架构模式：
  • [... 300字 ...]

API Design

API设计

When designing APIs:
  • [... 250 words ...]
设计API时：
  • [... 250字 ...]

Database Design

数据库设计

For database schemas:
  • [... 200 words ...]
对于数据库模式：
  • [... 200字 ...]

Testing Strategy

测试策略

Plan testing approach:
  • [... 200 words ...]

**Token count**: ~700 tokens

**After:**
```markdown
规划测试方法：
  • [... 200字 ...]

**Token数量**：~700token

**之后：**
```markdown

Relevant Skills

相关Skill

You have access to these specialized skills when planning:
  • api-design: REST API patterns, versioning strategies
  • database-design: Schema design, query optimization
  • testing-guide: Test strategy, coverage planning
Note: Skills load automatically based on task keywords.

**Token count**: ~130 tokens

**Savings**: 570 tokens (81% reduction)
当进行规划时，你可以使用以下专业Skill：
  • api-design：REST API模式、版本化策略
  • database-design：模式设计、查询优化
  • testing-guide：测试策略、覆盖率规划
注意：Skill会根据任务关键词自动加载。

**Token数量**：~130token

**节省**：570token（减少81%）

Detailed Documentation

详细文档

For comprehensive skill integration guidance:
  • Skill Discovery: See docs/skill-discovery.md for keyword matching and activation
  • Skill Composition: See docs/skill-composition.md for combining skills
  • Progressive Disclosure: See docs/progressive-disclosure.md for architecture details
如需全面的Skill集成指南：
  • Skill发现：查看[docs/skill-discovery.md]了解关键词匹配和激活机制
  • Skill组合：查看[docs/skill-composition.md]了解Skill组合方式
  • 渐进式披露：查看[docs/progressive-disclosure.md]了解架构细节

Examples

示例资源

  • Agent Template: See examples/agent-skill-reference-template.md
  • Composition Example: See examples/skill-composition-example.md
  • Architecture Diagram: See examples/progressive-disclosure-diagram.md
  • Agent模板：查看[examples/agent-skill-reference-template.md]
  • 组合示例：查看[examples/skill-composition-example.md]
  • 架构图：查看[examples/progressive-disclosure-diagram.md]

Integration with autonomous-dev

与autonomous-dev的集成

All 20 agents in the autonomous-dev plugin follow this skill integration pattern:
  • Each agent lists 3-7 relevant skills
  • No inline skill content duplication
  • Progressive disclosure prevents context bloat
  • Scales to 100+ skills without performance issues
Result: 20-30% token reduction in agent prompts while maintaining full access to specialized knowledge.
Version: 1.0.0 Type: Knowledge skill (no scripts) See Also: python-standards, testing-guide
autonomous-dev插件中的所有20个Agent均遵循此Skill集成模式：
  • 每个Agent列出3-7个相关Skill
  • 无内联Skill内容重复
  • 渐进式披露避免上下文冗余
  • 可扩展到100+个Skill且无性能问题
结果：Agent提示词的Token减少20-30%，同时仍能完整访问专业知识。
版本：1.0.0 类型：知识Skill（无脚本） 相关Skill：python-standards, testing-guide

Hard Rules

硬性规则

FORBIDDEN:
  • Skills without YAML frontmatter (name, version, type, keywords)
  • Skills exceeding 500 lines in the index SKILL.md (use progressive disclosure)
  • Circular skill dependencies
  • Skills that modify system state without declaring it in allowed-tools
REQUIRED:
  • All skills MUST have enforcement language (FORBIDDEN/REQUIRED sections)
  • All skills MUST declare keywords for auto-activation
  • Skills MUST be registered in agent frontmatter to be wired
  • Skill content MUST be self-contained (no broken cross-references)
禁止：
  • 无YAML前置元数据（name、version、type、keywords）的Skill
  • 索引SKILL.md超过500行的Skill（使用渐进式披露）
  • Skill循环依赖
  • 未在allowed-tools中声明就修改系统状态的Skill
要求：
  • 所有Skill必须包含强制规则（FORBIDDEN/REQUIRED章节）
  • 所有Skill必须声明用于自动激活的关键词
  • Skill必须在Agent前置元数据中注册才能生效
  • Skill内容必须自包含（无无效交叉引用）