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: 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"
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 complianceBenefits:
- 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. **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 progressivelySkill 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)
- **python-standards**: Documentation standards (docstrings and code style)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 skil