playbooks

home / skills / hotovo / aider-desk / skill-creator

skill-creator skill

/.aider-desk/skills/skill-creator

This skill helps you design effective Agent Skills using progressive disclosure, reducing complexity and accelerating skill architecture planning.

npx playbooks add skill hotovo/aider-desk --skill skill-creator

Review the files below or copy the command above to add this skill to your agents.

Files (7)
SKILL.md
1.6 KB
---
name: skill-creator
# prettier-ignore
description: Design and create Agent Skills using progressive disclosure principles. Use when building new skills, planning skill architecture, or writing skill content.
---

# Skill Creator

Create effective Agent Skills using progressive disclosure.

## When to Create a Skill

Create a skill when you notice:

- **Repeating context** across conversations
- **Domain expertise** needed repeatedly
- **Project-specific knowledge** the agent should know automatically

## Progressive Disclosure

Skills load in 3 levels:

1. **Metadata** (~27 tokens) - YAML frontmatter for triggering
2. **Instructions** (<680 tokens) - SKILL.md body with core patterns
3. **Resources** (unlimited) - references/ scripts/ assets/ loaded on
   demand

**Key**: Keep Levels 1 & 2 lean. Move details to Level 3.

## Structure

```
my-skill/
├── SKILL.md       # Core instructions + metadata
├── references/    # Detailed docs (loaded as needed)
├── scripts/       # Executable operations
└── assets/        # Templates, images, files
```

## References

- [quick-start.md](references/quick-start.md) - Creating your first
  skill
- [writing-guide.md](references/writing-guide.md) - Writing effective
  skills
- [development-process.md](references/development-process.md) -
  Step-by-step workflow
- [skill-examples.md](references/skill-examples.md) - Patterns and
  examples
- [cli-reference.md](references/cli-reference.md) - CLI tool usage
- [agent-skills-resources.md](references/agent-skills-resources.md) -
  Architecture and best practices

Overview

This skill helps you design and create Agent Skills using progressive disclosure principles. It focuses on keeping trigger metadata and core instructions lean while offloading detailed content to external resources. Use it to standardize skill architecture and streamline authoring for developer-focused AI agents.

How this skill works

The skill defines a three-level loading model: compact trigger metadata, concise core instructions, and on-demand detailed resources. Triggers and core patterns remain small to keep token use efficient, while extensive documentation, scripts, and assets are stored separately and fetched only when needed. This keeps runtime prompts focused and ensures maintainability as capabilities grow.

When to use it

  • You notice repeated context or tasks across agent conversations
  • A domain or team needs consistent, reusable agent behavior
  • You’re planning the architecture for multiple related skills
  • You need to offload large documentation, templates, or scripts
  • You want predictable triggering with minimal prompt overhead

Best practices

  • Keep metadata under ~30 tokens to optimize trigger matching
  • Limit core instructions to essential patterns and examples (<680 tokens)
  • Put step-by-step guides, code, and assets in separate resource folders
  • Use clear naming and a consistent folder layout for discoverability
  • Design triggers to be specific enough to avoid false positives

Example use cases

  • Create a repository-specific dev assistant with project knowledge loaded on demand
  • Extract recurring troubleshooting flows into a reusable skill
  • Bundle common developer commands and scripts so the agent can run them when authorized
  • Provide language- or domain-specific editing guidelines without bloating prompts
  • Build onboarding helpers that reveal deeper training materials only when requested

FAQ

How small should trigger metadata be?

Keep it compact—aim for a few tokens that reliably match intent without including detailed instructions.

What goes into the core instructions versus resources?

Core instructions include essential behavior patterns, guardrails, and short examples. Put long tutorials, sample code, templates, and heavy references in resources loaded on demand.