Agent Skills Guide

Progressive disclosure architecture for specialized knowledge that loads on-demand to optimize token usage.

Overview

Agent skills enable progressive disclosure - loading specialized knowledge only when needed, significantly reducing token usage while maintaining deep expertise.

Token Efficiency:

Architecture:

Tier 1: Metadata (always loaded)
   ↓ 50 tokens - name, description, triggers
Tier 2: Instructions (loaded when activated)
   ↓ 1,800-3,200 tokens - core patterns and guidance
Tier 3: Resources (loaded on deep-dive)
   ↓ 500-1,000 tokens - examples, templates, references

Available Skills

api-design-patterns

Agent: backend-architect Size: ~1,800 tokens Model Impact: Haiku-friendly (deterministic patterns)

Covers:

Use When:

CLI:

claude-ctx skills info api-design-patterns

microservices-patterns

Agent: backend-architect Size: ~3,200 tokens Model Impact: Sonnet-friendly (complex architecture)

Covers:

Use When:

CLI:

claude-ctx skills info microservices-patterns

Creating New Skills

Skill Development Workflow

1. Identify candidate
   ↓ Find 1000+ token knowledge chunk in agent

2. Extract and structure
   ↓ Create skill directory and SKILL.md

3. Write frontmatter
   ↓ Name, description with "Use when" triggers

4. Organize content
   ↓ Progressive tiers: essential → detailed → advanced

5. Link to agent
   ↓ Add skill to agent frontmatter

6. Validate
   ↓ claude-ctx skills validate skill-name

7. Document
   ↓ Update skills/README.md and this guide

Identifying Skill Candidates

Good candidates:

Examples:

✓ async-python-patterns (Python async programming)
✓ kubernetes-security-policies (K8s security best practices)
✓ graphql-schema-design (GraphQL patterns)
✓ ci-cd-pipeline-patterns (CI/CD best practices)

✗ "python basics" (too general, always needed)
✗ "code quality" (too vague, no clear triggers)
✗ "tips and tricks" (no structure, random knowledge)

Skill Structure Template

---
name: skill-name
description: What it covers. Use when [clear trigger criteria].
---

# Skill Title

Brief overview (1-2 paragraphs) explaining scope and purpose.

## When to Use This Skill

- Specific scenario 1
- Specific scenario 2
- Specific scenario 3
- Specific scenario 4
- Specific scenario 5

## Core Principles (Optional)

Foundational concepts that underpin the patterns.

## Fundamental Patterns (Tier 1 - Essential)

80% use cases, most common patterns.

### Pattern 1: Name
**Definition:** Brief explanation
**Example:** Code example with comments
**Benefits:** Why use this pattern
**Trade-offs:** When not to use

### Pattern 2: Name
...

## Advanced Patterns (Tier 2 - Detailed)

Complex scenarios, edge cases, performance optimization.

### Pattern N: Name
...

## Real-World Applications (Optional)

Practical examples showing patterns in production context.

## Anti-Patterns to Avoid

Common mistakes and how to prevent them.

## Best Practices Summary

Quick reference checklist.

## Resources

- Official documentation links
- RFCs, specifications
- Tools and libraries

Frontmatter Requirements

Required Fields:

---
name: skill-name                 # Hyphen-case, unique
description: Brief description. Use when [trigger]. # < 1024 chars
---

Validation Rules:

Examples:

✓ Good:

---
name: async-python-patterns
description: Python asyncio and concurrent programming patterns for high-performance applications. Use when building async APIs, concurrent systems, or I/O-bound applications requiring non-blocking operations.
---

✗ Bad:

---
name: Python_Async          # Wrong format (not hyphen-case)
description: Async patterns for Python.  # Missing "Use when", too vague
---

Token Budget Guidelines

Skill Complexity Token Range Use Case
Focused 500-1,500 Single pattern or technique
Standard 1,500-3,000 Set of related patterns
Comprehensive 3,000-5,000 Domain expertise
Specialized 5,000-8,000 Deep technical knowledge

Rule: If skill exceeds 8,000 tokens, split into multiple focused skills.

Examples by Size

Focused (500-1,500 tokens):

Standard (1,500-3,000 tokens):

Comprehensive (3,000-5,000 tokens):

Specialized (5,000-8,000 tokens):

Progressive Disclosure in Practice

Example: backend-architect + api-design-patterns

Scenario: User asks “Design a REST API for user management”

Without Skills (Old Way):

1. Load backend-architect.md (8,000 tokens)
   - API patterns (needed) ✓
   - Microservices (not needed) ✗
   - Event-driven (not needed) ✗
   - CQRS (not needed) ✗
   - Database patterns (not needed) ✗
Total: 8,000 tokens, 60% unused

With Skills (New Way):

1. Load backend-architect.md core (3,000 tokens)
   - Architecture principles ✓
   - Workflow guidance ✓

2. Detect "REST API" trigger → Activate api-design-patterns

3. Load api-design-patterns skill (1,800 tokens)
   - REST design ✓
   - Versioning ✓
   - Pagination ✓
   - Error handling ✓

Total: 4,800 tokens, 0% waste
Savings: 40%

Skill Composition

Skills can reference other skills for complex workflows:

User: "Build a microservices-based e-commerce platform"

1. backend-architect activates
2. Loads skills in sequence:
   - api-design-patterns (service contracts)
   - microservices-patterns (architecture)
   - event-driven-architecture (async communication)

3. Coordinates with other agents:
   - database-optimizer (data patterns)
   - kubernetes-architect (deployment)
   - security-auditor (security validation)

Integration with Agents

Agent Frontmatter

---
name: backend-architect
# ... other fields ...
skills:                          # NEW field
  - api-design-patterns          # Skill 1
  - microservices-patterns       # Skill 2
  - event-driven-architecture    # Skill 3
---

Activation Logic

Automatic (Keyword-Based):

User message contains:
  "REST API" → api-design-patterns
  "microservices" → microservices-patterns
  "event-driven" → event-driven-architecture

Explicit (Agent-Requested):

Agent determines it needs specific knowledge:
  "I need guidance on API versioning strategies"
  → Load api-design-patterns

Context-Driven (Project Detection):

Project type: FastAPI microservices
  → Automatically suggest:
     - api-design-patterns
     - microservices-patterns
     - async-python-patterns

CLI Commands

# List all available skills
claude-ctx skills list

# Show skill details
claude-ctx skills info api-design-patterns

# Validate skill metadata
claude-ctx skills validate api-design-patterns

# Validate all skills
claude-ctx skills validate --all

# Show which agents use a skill (future)
claude-ctx skills deps api-design-patterns

Quality Checklist

Before committing a new skill, verify:

Skill Roadmap

Phase 1: Foundation ✅ COMPLETED

Phase 2: Core Skills ✅ COMPLETED

Architecture & Design (4 skills):

Infrastructure (5 skills):

Development (5 skills):

Security (4 skills):

Total Phase 2: 18 skills completed

Phase 3: Integration ✅ COMPLETED

Features Delivered:

New Commands:

Phase 4: Advanced ✅ COMPLETED

Features Delivered:

New Commands:

Metrics & Analytics

Token Efficiency

Agent Without Skills With Skills Savings
backend-architect 8,000 tokens 4,800 tokens 40%
kubernetes-architect 7,500 tokens ~4,500 tokens 40%
security-auditor 6,800 tokens ~4,500 tokens 34%
deployment-engineer 7,200 tokens ~4,800 tokens 33%

Aggregate Savings: 35-40% across heavyweight agents

Skill Usage Patterns

Track skill activation frequency to prioritize future skills:

Best Practices

For Skill Authors

  1. Start with “When to Use”: Clear activation criteria prevent confusion
  2. Progressive Structure: Essential patterns first, advanced later
  3. Practical Examples: Show don’t tell with code examples
  4. Link Official Docs: Point to authoritative sources
  5. Token Budget: Keep under 5K for standard skills
  6. Avoid Duplication: Reference other skills instead of repeating
  7. Update Regularly: As patterns evolve, update skills
  8. Validate Often: Run validation before committing

For Skill Users

  1. Check Available Skills: claude-ctx skills list before creating agents
  2. Link Skills: Add relevant skills to agent frontmatter
  3. Monitor Usage: Track which skills activate most frequently
  4. Provide Feedback: Report skill effectiveness to maintainers
  5. Suggest New Skills: Identify patterns that warrant extraction

FAQs

Q: When should I create a skill vs. keeping knowledge in agent? A: Create a skill if knowledge is:

Q: Can multiple agents use the same skill? A: Yes! That’s a key benefit. api-design-patterns could be used by backend-architect, api-documenter, and code-reviewer.

Q: How do I know if a skill is being loaded? A: Currently via agent behavior. Future: skill activation metrics in logs.

Q: What if my skill exceeds 8,000 tokens? A: Split into multiple focused skills. Example: “microservices-patterns” + “microservices-resilience” + “microservices-observability”

Q: Can skills reference other skills? A: Not yet, but planned for Phase 4 (skill composition).

Q: How often should skills be updated? A: Review quarterly, update when:

Q: Can I contribute skills? A: Yes! Follow the creation workflow, validate, and submit PR.

Examples from ~/agents

The ~/agents marketplace has 47 skills across 14 plugins. Key examples:

Python Development (5 skills):

Kubernetes (4 skills):

Backend (3 skills):

LLM Applications (4 skills):

These serve as excellent reference implementations.

Resources