name	skill-integration
type	knowledge
description	Standardized patterns for how agents discover, reference, and compose skills using progressive disclosure architecture
keywords	skill, skills, progressive disclosure, skill discovery, skill composition, agent integration, skill reference
auto_activate	true

Skill Integration Skill

Standardized patterns for how agents discover, reference, and use skills effectively in Claude Code 2.0+.

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"

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

Progressive Disclosure Architecture

What It Is

Progressive disclosure is a design pattern where:

Metadata stays in context - Skill names, descriptions, keywords (~50 tokens)
Full content loads on-demand - Detailed guidance only when needed (~5,000-15,000 tokens)
Context stays efficient - Support 50-100+ skills without bloat

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

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!                                        │
└─────────────────────────────────────────────────────────┘

Skill Discovery Mechanism

Keyword-Based Activation

Skills auto-activate when task keywords match skill keywords:

Example: testing-guide skill

---
name: testing-guide
keywords: test, testing, pytest, tdd, coverage, fixture
auto_activate: true
---

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"

Manual Skill Reference

Agents can explicitly reference skills in their prompts:

## Relevant Skills

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 Composition

Combining Multiple Skills

Complex tasks often require multiple skills:

Example: Implementing authenticated API endpoint

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. **documentation-guide** - API 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 Layering

Skills can reference other skills:

## Relevant Skills

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

Benefits:

Natural skill hierarchy
Agent discovers related skills automatically
No need to list every transitive dependency

Standardized Agent Skill References

Template Format

Every agent should include a "Relevant Skills" section:

## Relevant Skills

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.

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"

Example: implementer Agent

## Relevant Skills

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)

Token Reduction Benefits

Per-Agent Savings

Typical agent with verbose "Relevant Skills" section:

Before (verbose inline guidance):

## Relevant Skills

### Testing Patterns
- Use pytest for all tests
- Follow Arrange-Act-Assert pattern
- Use fixtures for setup
- Aim for 80%+ coverage
- [... 300 more words ...]

### Code Style
- Use black for formatting
- Add type hints to all functions
- Write Google-style docstrings
- [... 200 more words ...]

### Security
- Validate all inputs
- Use parameterized queries
- [... 150 more words ...]

Token count: ~500 tokens

After (skill references):

## Relevant Skills

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)

Across All Agents

20 agents × 350 tokens saved = 7,000 tokens
Plus: Skills themselves deduplicate shared guidance
Result: 20-30% overall token reduction in agent prompts

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

Real-World Examples

Example 1: researcher Agent

Before:

## Relevant Skills

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

## Relevant Skills

You have access to these specialized skills when researching:

- **research-patterns**: Web research methodology, source evaluation
- **documentation-guide**: Documentation standards for research findings

**Note**: Skills load automatically based on task keywords.

Token count: ~100 tokens

Savings: 500 tokens (83% reduction)

Example 2: planner Agent