skill-creator

Files (28)

• README.md
• SKILL.md
• analyzer.md · agents/
• comparator.md · agents/
• grader.md · agents/
• eval_review.html · assets/
• viewer.html · assets/
• evals.json · evals/
• SKILL.md · evals/files/incident-summary/
• SKILL.md · evals/files/pdf-forms/
• trigger-eval.json · evals/
• description-optimization.md · references/
• host-adaptations.md · references/
• running-evals.md · references/
• schemas.md · references/
• scripts.md · references/
• writing-skills.md · references/
• aggregate_benchmark.py · scripts/
• copilot_cli.py · scripts/
• generate_report.py · scripts/
• generate_review.py · scripts/
• improve_description.py · scripts/
• package_skill.py · scripts/
• prepare_eval_review.py · scripts/
• quick_validate.py · scripts/
• run_eval.py · scripts/
• run_loop.py · scripts/
• utils.py · scripts/

SKILL.md (first lines)

# Skill Creator

Use this skill to create and improve portable Agent Skills that follow the
Agent Skills format. The main loop is:

1. Find out what the skill must do and roughly how.
2. Write a draft of the skill.
3. Run the skill in the intended agent or harness on realistic test prompts.
4. Help the user review the results, both by reading the outputs and with
   benchmark numbers.
5. Change the skill based on the feedback. Repeat until the user is satisfied.
6. Optionally, optimize the description so that the skill triggers reliably.

Generated skills follow the Agent Skills format and should be client-neutral by
default. Add client-specific frontmatter, installation paths, tools or commands
only when the user targets that client or its compatibility requires them.

Find out where the user is in this loop and continue from there. If they have
only an idea, help them define it and write a draft. If they already have a
draft, go to testing. If they say they do not want formal evals, work
informally with them. The order is flexible.

Match the user's level of expertise. Briefly explain evaluation terms that may
be new to them. For the review tools, describe app-specific behavior, such as
focus changes and save status, and do not explain basic keyboard use.

## Create a skill

### Capture the intent

The conversation may already contain the workflow that the user wants to keep,
for example "turn this into a skill". If so, take the tools, steps,
corrections and input and output formats from the conversation first. Ask the
user to fill the gaps and confirm before you continue. Find out:

1. What the skill must let an agent do and which client(s) it targets. Default
   to cross-client Agent Skills compatibility unless the user says otherwise.
2. When the skill must trigger: which user phrases and contexts.
3. What output format is expected.
4. Whether to set up test cases. Skills with outputs that can be checked
   objectively (file conversions, data extraction, code generation, fixed
   workflows) benefit from test cases. Skills with subjective outputs (writing
   style, art) often do not. Suggest a default for the skill type, and let the
   user decide.

Start from real expertise, not general knowledge. A skill built only from what
the model already knows gives vague advice. Ask for project material: runbooks,
style guides, API specifications and schemas, incident reports, code review
comments and fixes in version control history. A real task done hands-on in
the conversation is also good material: keep the steps that worked, the
corrections the user made and the facts the agent did not know.

Ask about edge cases, input and output formats, example files, success
criteria and dependencies before you write test prompts. If MCP servers or
subagents are available, use them to research documentation, similar skills
and best practices, in parallel where possible. Bring this context to the
conversation so the user has less to explain.

### Write the SKILL.md

Read `references/writing-skills.md` before you write a new skill or make a
large change. It has the frontmatter field rules, YAML pitfalls, staged
loading and the writing style guide. The essentials:

- Use `.agents/skills/<skill-name>/SKILL.md` as the default project location
  for cross-client portability. Use a client's native location only when the
  user targets that client.
- `name`: 1-64 lowercase letters, digits and hyphens, the same as the
  directory name. `description`: 1-1024 characters. Add other frontmatter
  fields only when needed, and client-specific fields only when the user
  targets that client.
- **The description is the trigger.** Write it as "Use this skill when…",
  describe what the user wants to achieve, list contexts that do not name the
  domain, and add near-miss exclusions. Then test it with real queries.
- Keep the body under about 5000 tokens and 500 lines. Move details into
  `references/` and say in SKILL.md exactly when to read each file.
- Add what the agent lacks and omit what it knows. Include a **Gotchas**
  section in SKILL.md and a checklist for multi-step workflows.
- Read `references/scripts.md` before you write or change a bundled script.

After you write or change a skill, validate it and fix every error and
warning:

```powershell
python scripts/quick_validate.py "<path-to-skill>"
```

### Write test cases

Agree with the user to include task evals before adding them. A request to
draft or edit a skill does not by itself authorize test files. Show proposed
prompts in the conversation and wait for approval before saving or running
them, so the user can correct the test scope before it becomes a fixture.

Write 2 or 3 realistic test prompts: the kind of thing a real user would say.
Vary the phrasing, the level of detail and the formality. Include at least one
edge case, such as a malformed input or an unusual request.
Show them to the user, for example: "Here are a few test cases I'd like to
try. Do these look right, or do you want to add more?" After approval, save them to
`evals/evals.json`:

```json
{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": [],
      "assertions": []
    }
  ]
}
```

Leave `assertions` empty for now. You write them while the first runs are in
progress. See `references/schemas.md` for the full format. These task evals are
not the same as the trigger queries for description optimization.

From akash07k/skills, AGPL-3.0.

More from akash07k/skills