Create Skill

Create Skill

Create agent skills that are portable, easy to trigger, and cheap to load. A skill is a folder containing a SKILL.md file with YAML frontmatter and markdown instructions.

Workflow

1. Intake (mandatory gate) — Understand what the skill

should do. Ask at least 3 targeted questions before drafting anything. Collect:

• A short name (lowercase, hyphenated)
• What the skill enables the agent to do
• When it should activate (trigger conditions)
• What success looks like

Summarize your understanding and get explicit confirmation before proceeding. Do not write SKILL.md until the user confirms.

1. Investigate the repo — Before asking questions, search the

repo for:

• Existing skills, conventions, and workflow docs
• Scripts, templates, schemas relevant to the target workflow
• Tool or dependency requirements
• Whether the conversation already contains a workflow to

capture

1. Clarify — Ask only questions that materially affect the

skill. Push until these are clear:

• Required workflow steps and their order
• Required inputs and expected outputs
• Dependencies on tools, scripts, or services
• Whether the skill needs references/, scripts/, or

assets/

1. Design the package — Structure:

``text skill-name/ ├── SKILL.md # Metadata + core workflow ├── references/ # Detailed docs, loaded on demand ├── scripts/ # Executable code └── assets/ # Templates, resources ``

• Keep SKILL.md under 500 lines
• Move bulky detail into references/
• Put deterministic execution in scripts/
• Don't duplicate guidance across files

1. Write SKILL.md — Structure:

``markdown --- name: skill-name description: > What the skill does and produces. Use when the user wants to , mentions , or asks about . --- ``

Frontmatter rules:

• Required: name and description in frontmatter.

Other fields depend on your project's conventions.

• Version in frontmatter is always "1.0.0" for new

skills. Never use 0.x.y — first release is 1.0.0.

• CHANGELOG.md starts with ## [Unreleased] containing

the initial entries. Do not assign a version heading until the skill is actually released (git tagged).

Writing rules:

• Description optimizes activation, not teaching. State

the job and when to use it in words a user would actually say. Include both actions and situations. Keep workflow details out of the description.

Bad: Follows a 7-step process to generate SKILL.md files with YAML frontmatter.

Good: Creates agent skills. Use when the user wants to build a SKILL.md, turn a workflow into a reusable skill, or is frustrated by inconsistent agent behavior.

• Body is procedural and imperative. Tell the agent

exactly how to proceed. Don't restate trigger criteria from the description — a "When to use" section in the body duplicates the description.

• Use imperative form. "Do not", "Use", "Run" — not

"prefer" or "consider".

• Be concise. Terse reminders, not tutorials.
• Include a complete example. One full, copy-paste-ready

artifact beats scattered snippets.

• Include a Boundaries section (mandatory). List what

the skill DOES and Does NOT do.

• Include a Common Failures section. List 2–3

domain-specific mistakes an agent would make without this guidance.

See [example-skill.md](references/example-skill.md) for a complete finished skill demonstrating these principles.

1. Validate — Test the skill with representative prompts:

• 2–3 realistic positive prompts (things users would say)
• At least 1 negative prompt (adjacent but shouldn't trigger)

Write a brief validation report noting:

• Which prompts triggered correctly
• Which failed and why (trigger wording, workflow ambiguity,

or missing resources)

• What was fixed based on the failures

Skip validation only for trivial skills where the trigger surface is obvious.

Portability check — For distributable skills, verify:

• No hardcoded project-specific paths (use discovery)
• No project-specific terminology (internal jargon)
• No references to specific rules/tools only in your repo
• Instructions work in any repo with any directory layout

1. Acknowledge sources — If the skill draws on external

practices, create references/ACKNOWLEDGMENTS.md listing each source with a link, license, what was adapted, and the version it was adopted in.

1. Confirm — Show the user the created skill and ask if

adjustments are needed.

Boundaries

• DOES create skill directories, SKILL.md, references/, scripts/
• DOES validate with representative prompts
• Does NOT modify existing skills
• Does NOT create rules or profiles (separate workflows)

Example Scenario

User: "Turn my database migration steps into a skill." → Investigate repo (Flyway config) → ask about rollback scope → create migrate-database/SKILL.md → validate with prompts.

Common Failures

• Description leaks workflow — the agent reads the summary

and skips the body, following a shortcut instead of the full procedure.

• Body too abstract to act on — "investigate the problem"

isn't actionable. "Run git log --oneline -20 to check recent patterns" is.

• Weak enforcement in instructions — If evals show the

agent ignoring a step, add it to a Common Failures section with NEVER/MUST language. Explicit failure modes with strong directives are more effective than polite workflow steps.

Quality Checklist

Before finalizing, use the [skill design checklist](references/skill-design-checklist.md), [skill validation](references/skill-validation.md), and [token optimization](references/token-optimization.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tovrleaf
• Source: tovrleaf/openkata
• License: MIT

Install and usage instructions live in the source repository linked above.