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

• python-standards: 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

Before:

Relevant Skills

Architecture Patterns

Follow these architectural patterns:

• [... 300 words ...]

API Design

When designing APIs:

• [... 250 words ...]

Database Design

For database schemas:

• [... 200 words ...]

Testing Strategy

Plan testing approach:

• [... 200 words ...]

Token count: ~700 tokens

After:

Relevant Skills

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)

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

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

Integration with 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

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)