skill-creator

Files (5)

• SKILL.md
• frontmatter.md · references/
• patterns.md · references/
• testing.md · references/
• validate_skill.py · scripts/

SKILL.md (first lines)

# Skill Creator

A skill is a folder that teaches an agent how to handle a specific task or workflow:

```
your-skill-name/
├── SKILL.md       # Required — YAML frontmatter + Markdown instructions
├── scripts/       # Optional — executable code (Python, Bash, ...)
├── references/    # Optional — docs loaded only when needed
└── assets/        # Optional — templates, fonts, icons used in output
```

Skills rely on **progressive disclosure**: the frontmatter is always in context (so it decides *when* the skill loads), the SKILL.md body loads when relevant, and linked files load only on demand. Keep each level as small as it can be.

## Workflow: Creating a New Skill

### Step 1: Define 2-3 concrete use cases

Before writing anything, pin down with the user:

- What does the user want to accomplish? (outcome, not feature)
- What triggers it? Collect literal phrases users would say.
- What steps does the workflow require, in order?
- Which tools are needed (built-in, scripts, MCP servers)?
- What domain knowledge or best practices must be embedded?

Write each use case as: **Trigger → Steps → Result**. If the user is vague, propose use cases and confirm rather than guessing silently.

Identify the category — it shapes the structure:

1. **Document & asset creation** — embed style guides, templates, quality checklists.
2. **Workflow automation** — step-by-step process with validation gates.
3. **MCP enhancement** — orchestrate MCP tool calls in sequence with domain expertise.

### Step 2: Plan the folder structure

- Folder name: kebab-case only (`my-skill` — no spaces, capitals, or underscores) and it should match the frontmatter `name`.
- `SKILL.md` must be named exactly that, case-sensitive.
- Never put a `README.md` inside the skill folder.
- Keep SKILL.md under ~5,000 words; move detail to `references/` and link to it.
- For critical validations, prefer a bundled script over prose — code is deterministic, language interpretation isn't.

### Step 3: Write the frontmatter

The frontmatter is the single most important part — it alone decides whether the skill ever loads.

```yaml
---
name: your-skill-name
description: [What it does] + [When to use it, with literal trigger phrases] + [negative triggers if needed]
---
```

Rules (hard requirements):

- `description` MUST state both WHAT the skill does and WHEN to use it, under 1024 characters.
- Include specific phrases users would actually say, and file types if relevant.
- No XML angle brackets anywhere in frontmatter (it is injected into the system prompt).
- `name` must not use reserved prefixes ("claude", "anthropic").

Weak: `description: Helps with projects.`
Strong: `description: Manages Linear sprint workflows including planning, task creation, and status tracking. Use when the user mentions "sprint", "Linear tasks", or asks to "create tickets".`

For all optional fields (`license`, `compatibility`, `metadata`, `allowed-tools`) and more good/bad examples, read `references/frontmatter.md`.

### Step 4: Write the instructions

Recommended body structure:

```markdown
# Skill Name

## Instructions
### Step 1: [First major step]
Exact commands / tool calls, with expected output described.

## Examples
User says X → actions → result.

## Troubleshooting
Error → cause → fix.
```

Best practices:

- Be specific and actionable: give exact commands with flags and expected output, not vibes ("validate the data").
- Put critical instructions at the top; use `## Important` headers for must-not-skip rules.
- Include error handling for the failures users will actually hit.
- Reference bundled resources explicitly ("Before writing queries, read the API-patterns file in references/").
- Number steps that must happen in order; state data dependencies between steps.

For proven structural patterns (sequential orchestration, multi-MCP coordination, iterative refinement, context-aware tool selection, domain-specific intelligence), read `references/patterns.md`.

### Step 5: Validate

Run the bundled validator on the skill folder:

```bash
python scripts/validate_skill.py /path/to/your-skill-name
```

It checks naming, frontmatter format and length, forbidden content, missing linked files, and body size. Fix every ERROR; treat WARNINGs as review prompts. Expected output on success: `PASS` with 0 errors.

### Step 6: Test and iterate

Iterate on a single challenging task until it succeeds, then extract the winning approach into the skill — this gives faster signal than broad testing. Then cover:

1. **Triggering**: obvious phrasing loads it, paraphrases load it, unrelated queries don't.
2. **Function**: outputs correct, tool calls succeed, edge cases handled.
3. **Baseline comparison**: fewer corrections / tool calls / tokens than without the skill.

Debugging trick: ask the agent "When would you use the [name] skill?" — it will paraphrase the description back; fix what's missing.

Full test-case templates and iteration signals are in `references/testing.md`.

## Workflow: Reviewing an Existing Skill

When asked to review or improve a skill:

From arborlogic/openzerocode, MIT.

More from arborlogic/openzerocode