Skill Creator

Skill Creator

A skill for creating and iteratively improving skills.

The Skill Lifecycle

1. Capture intent — understand what the skill should do and when it should trigger
2. Write a draft — compose the SKILL.md with frontmatter + instructions
3. Test it — run realistic prompts through the skill and evaluate the results
4. Iterate — rewrite based on feedback and test again
5. Polish — optimize the description for triggering accuracy

Your job is to figure out where the user is in this process and help them progress.

Communicating with the user

Pay attention to context cues. Not every user is a programmer — some may be using octo for the first time. Briefly explain terms if you're in doubt.

Creating a skill

Capture Intent

Start by understanding the user's intent. The current conversation may already contain a workflow they want to capture.

Ask:

1. What should this skill enable octo to do?
2. When should this skill trigger? (what user phrases / contexts)
3. What's the expected output format?
4. Should we set up test cases? Skills with objectively verifiable outputs (file transforms, code generation, fixed workflow steps) benefit from tests. Skills with subjective outputs (writing style, creative tasks) often don't.

Interview and Research

Proactively ask about edge cases, input/output formats, example files, success criteria, and dependencies.

Check available skills and tools — if useful for research, use subagents to search docs or find similar skills in parallel.

Where the skill lives

A skill is a directory holding a SKILL.md under ~/.octo/skills/<name>/SKILL.md — available in every session, regardless of which project you're working in. octo skills add and the web Skills panel install here.

Write the SKILL.md

The format is a SKILL.md with YAML frontmatter:

---
name: my-skill
description: When to trigger, what it does. Be specific — include both what the skill does AND the contexts where it should be used. Make descriptions slightly "pushy" to combat undertriggering.
---

# Title

Instructions go here...

Anatomy of a skill:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable scripts for deterministic tasks
    ├── references/ - Docs loaded into context as needed
    └── templates/  - Files used in output

Progressive Disclosure:

• Metadata (name + description) — Always in the system prompt (~100 words)
• SKILL.md body — Loaded on demand when the skill triggers (<500 lines ideal)
• Bundled resources — Read on demand with file tools

Key patterns:

• Keep SKILL.md under 500 lines
• Reference bundled files clearly with guidance on when to read them
• For large reference files (>300 lines), include a table of contents
• Use imperative form in instructions
• Explain the why behind instructions, not just the what
• Avoid ALL-CAPS MUSTs — explain reasoning instead

Defining output formats:

## Report structure
Always use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

Test the skill

After writing the draft, come up with 2–3 realistic test prompts. Share them with the user for approval, then test.

How to test in octo:

1. Create a test workspace directory
2. For each test prompt, spawn a subagent:
   • Give it the skill path (~/.octo/skills/<name>/)
   • Give it the test prompt as a task
   • Have it save outputs to a designated directory
3. Review outputs — both qualitatively and, if possible, with simple assertions
4. Collect feedback and iterate

If the user says "don't overthink it, just vibe with me," skip formal testing and iterate conversationally instead.

Improving a skill

How to think about improvements

1. Generalize from feedback — skills are meant to be used thousands of times. Don't overfit to test cases; fix the underlying pattern.
2. Keep the prompt lean — remove instructions that aren't pulling their weight. Read the full execution trace, not just final outputs.
3. Explain the why — today's LLMs are smart. Give them reasoning and they'll go beyond rote instructions.
4. Look for repeated work — if test runs all independently wrote similar helper scripts, bundle one in scripts/.