Skip to content
LiveNew tools this week
Submit
AIMarketly
Skill Integration logo

Skill Integration

Standardizes how AI agents discover, reference, and compose skills using a progressive disclosure architecture.

akaszubski/autonomous-dev7installs34stars

SKILL.md

Full skill instructions

name version type description keywords auto_activate allowed-tools

skill-integration

1.0.0

knowledge

Standardized patterns for how agents discover, reference, and compose skills using progressive disclosure architecture

skill, skills, progressive disclosure, skill discovery, skill composition, agent integration, skill reference

true

Read

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

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:

  • ** architecture-patterns ** : Design patterns, SOLID principles
  • ** 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 : agent-output-formats, documentation-guide, python-standards