Skills

Skills solve three problems:

1. Constrain agents — "This agent should only use testing tools, not web_search"
2. Bundle knowledge — Package tool-specific instructions with the tools
3. Reuse patterns — Create once, use in multiple agents

Each skill lives in a directory with a SKILL.md file.

agents/{agent-name}/skills/{skill-name}/
  SKILL.md              # Skill definition
  scripts/              # Optional verification scripts
    verify-tools.sh

SKILL.md is a markdown file with YAML frontmatter:

---
name: test-helper
description: Skill for testing Rush app features
allowed-tools:
  - sqlite
  - delegate
---

# Test Helper Skill

## Testing Protocol

When testing a tool:
1. Call with minimal valid input
2. Validate response structure
3. Test edge cases
4. Document results

Declare skills in agent.yaml:

tools:
  - name: sqlite
  - name: delegate
  - name: web_search

skills:
  - name: test-helper
    config: {}

What happens:

• Agent declares 3 tools (sqlite, delegate, web_search)
• test-helper restricts to: sqlite + delegate only
• web_search becomes unavailable
• Agent gets read_skill tool for on-demand access to full instructions

Skills use progressive disclosure to save context tokens:

• System prompt only shows skill name + description
• Agent calls read_skill(name: "test-helper") when it needs full instructions
• Full SKILL.md content is returned on demand

When multiple skills are declared, allowed tools are merged (union):

skills:
  - name: test-helper      # Allows: sqlite, delegate
  - name: web-researcher   # Allows: web_search, web_fetch
# Result: agent can use sqlite, delegate, web_search, web_fetch

• Name skills after their purpose: test-helper, web-researcher, not skill-1
• Keep SKILL.md focused on the specific tools and workflows
• Use allowed-tools for enforcement, don't just document restrictions
• Include examples showing how to use the tools effectively