Skill Creator

This skill helps you create, refine, and evaluate Agent Skills following the agentskills.io open standard.

Skill Structure

A skill is a directory containing a SKILL.md file. Optional directories add more capabilities:

skill-name/
├── SKILL.md          # Required: frontmatter + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── evals/            # Optional: test cases
    └── evals.json

Creating a New Skill

1. Choose a name

• Lowercase letters, numbers, and hyphens only
• 1-64 characters
• Must not start or end with a hyphen
• Must match the parent directory name

2. Write the frontmatter

---
name: skill-name
description: A clear description of what this skill does and when to use it.
---

3. Write instructions in the body

Recommended sections:

• Step-by-step instructions
• Examples of inputs and outputs
• Common edge cases (Gotchas)
• Output format templates
• Checklists for multi-step workflows

4. Create the directory

Place the skill at .agents/skills/<skill-name>/SKILL.md

Creating a Skill from the Current Conversation

The most effective skills come from real workflows where the user guided the agent and liked the results. Extract the reusable pattern from this conversation.

1. Review the interaction

Look back at what just happened in the conversation:

• Steps that worked — the sequence of actions that led to success
• Corrections the user made — places where they steered the approach ("use library X instead of Y", "check for edge case Z")
• Input/output formats — what data looked like going in and coming out
• Context the user provided — project-specific facts, conventions, or constraints you didn't already know

2. Generalize the workflow

Turn specific commands into parameterized instructions:

# Specific (from chat)
Run: python scripts/deploy.py --env production --tag v1.2.3

# Generalized (in skill)
Run: python scripts/deploy.py --env {environment} --tag {version}

Remove details specific to the one-off task. Keep the structure that made it work.

3. Capture gotchas immediately

Every correction the user gave mid-workflow should become a gotcha:

## Gotchas

- The `users` table uses soft deletes. Always include
  `WHERE deleted_at IS NULL`.
- The API key must be set as `X-API-Key` header, not `Authorization`.
- Never run migration step 2 before step 1 completes.

4. Write the SKILL.md

---
name: <workflow-name>
description: >
  <Describe the task the user just did, including keywords
   that would make this trigger again.>
---

## Workflow

<Step-by-step instructions extracted from the conversation>

5. Ask the user to confirm

Before finalizing, present the skill to the user:

• "I extracted this workflow into a skill at .agents/skills/<name>/SKILL.md"
• Summarize what it does and when it would trigger
• Ask if they want to refine the description, add edge cases, or test it

6. Refine with real execution

Run the new skill against a similar task. If the user corrects you again, update the gotchas. If the first run works well, the skill is ready.

Writing Effective Descriptions

The description field determines when the agent triggers your skill. Write it as an instruction to the agent:

description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use this
  skill when the user has a CSV, TSV, or Excel file and wants to
  explore, transform, or visualize the data, even if they don't
  explicitly mention "CSV" or "analysis."

Guidelines:

• Use imperative phrasing ("Use this skill when...")
• Focus on user intent, not implementation
• Err on the side of being pushy — list contexts explicitly
• Keep it concise (max 1024 chars)

Best Practices for Instructions

What to Include

• Gotchas: environment-specific facts that defy reasonable assumptions
• Templates: concrete output format examples
• Checklists: track progress in multi-step workflows
• Validation loops: do → validate → fix → repeat

What to Omit

• General knowledge the agent already has (what a PDF is, how HTTP works)
• Too many equal options — pick a default, mention alternatives briefly
• Exhaustive edge case coverage — let the agent use judgment

Progressive Disclosure

Keep SKILL.md under 500 lines / 5000 tokens. Move detailed reference material to references/ files and tell the agent when to load each one.

Bundling Scripts

One-off commands

Reference existing tools directly:

uvx [email protected] check .
npx eslint@9 --fix .

Self-contained scripts

Place in scripts/ with inline dependencies:

# /// script
# dependencies = ["beautifulsoup4"]
# ///

from bs4 import BeautifulSoup

Script design for agents

• No interactive prompts — accept all input via flags, env vars, or stdin
• Include --help output
• Write helpful error messages
• Use structured output (JSON, CSV)
• Separate data (stdout) from diagnostics (stderr)
• Support --dry-run for destructive operations

Running Evals

Test cases

Create evals/evals.json:

{
  "skill_name": "my-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "A realistic user prompt...",
      "expected_output": "What success looks like",
      "files": ["evals/files/input.csv"],
      "assertions": [
        "The output includes a chart image",
        "Both axes are labeled"
      ]
    }
  ]
}

Process

1. Run each test case with and without the skill
2. Grade assertions as PASS/FAIL with concrete evidence
3. Aggregate into benchmark.json (pass rate, timing, tokens)
4. Review outputs with a human
5. Iterate: eval → analyze → revise → re-eval

Description Optimization

1. Write ~20 queries (8-10 should-trigger, 8-10 should-not-trigger)
2. Split 60/40 into train/validation sets
3. Run each query 3x, compute trigger rate
4. Revise description based on train set failures
5. Validate against held-out validation set
6. Repeat ~5 iterations or until plateauing

Testing Trigger Accuracy

# Script to test description triggering
# Create eval_queries.json, then:
# - Run each query 3x
# - Check if skill was invoked
# - Compute trigger rate per query
# - Iterate on description

References

• Full specification
• Best practices
• Evaluating skills
• Optimizing descriptions
• Using scripts
• Adding skills support to agents