Skills System: Reusable AI Agent Capabilities

Skills are persistent markdown files that teach PocketPaw how to handle specific types of tasks. They’re loaded into the agent’s context on every interaction.

What is a Skill?

A skill is a SKILL.md file stored in ~/.claude/skills/ (the standard Claude SDK location). Each skill defines:

• When to activate — Trigger phrases or conditions
• How to execute — Step-by-step instructions
• What tools to use — Tool chains and sequences
• Output format — Expected response structure

Creating Skills

Via the Skill Generator Tool

The agent can create skills using the skill_gen tool:

User: Create a skill for writing daily standup summaries
Agent: [uses skill_gen] → Created skill: daily-standup.md

Manually

Create a markdown file in ~/.claude/skills/:

# Code Review Skill

## Trigger
When the user asks to review code, a PR, or a diff.

## Steps
1. Read the file or diff provided
2. Analyze for:
   - Bug risks
   - Performance issues
   - Security concerns
   - Code style
3. Provide structured feedback

## Output Format
### Summary
Brief overall assessment.

### Issues Found
- **[severity]** Description of issue (line X)

### Suggestions
- Improvement suggestions

Skill Loading

Skills are loaded by the SkillLoader and injected by the AgentContextBuilder:

1. On startup, all *.md files are scanned from three directories (in priority order):
   • ~/.agents/skills/ — central skills (from skills.sh)
   • ~/.claude/skills/ — Claude Code / SDK standard location
   • ~/.pocketpaw/skills/ — PocketPaw-specific (legacy)
2. Skill content is injected into the system prompt
3. The agent uses skills as reference when handling matching requests
4. After creating a new skill via skill_gen, the loader is reloaded

When using the Claude Agent SDK backend, skills are also auto-discovered via setting_sources — the SDK natively reads SKILL.md files from ~/.claude/skills/ and .claude/skills/ (project-level).

Skill Directory

~/.claude/skills/
├── daily-standup.md
├── code-review.md
├── meeting-notes.md
└── git-workflow.md

Best Practices

1. Keep skills focused — One skill per task type
2. Be specific — Clear trigger conditions prevent false matches
3. Include examples — Show the expected output format
4. Reference tools — Specify which tools to use
5. Test and iterate — Try the skill and refine it

Related