Skill Creator

Create and refine skills that work across agents implementing the Agent Skills specification.

Use imperative instructions. Keep the process deterministic where possible. Keep the skill output portable.

Objectives

• Produce a valid skill with a correct SKILL.md frontmatter and useful body instructions.

• Keep the skill agent-agnostic unless the user explicitly requests agent-specific behavior.

• Apply progressive disclosure so only essential content stays in SKILL.md .

• Validate structure and naming before declaring completion.

Workflow

1. Identify intent and scope

Determine whether the user wants one of these outcomes:

• New skill from scratch

• Update an existing skill

• Improve trigger quality (description tuning)

• Add reusable resources (scripts/ , references/ , assets/ )

Extract known constraints from conversation context first. Only ask for missing details that materially change implementation.

2. Gather concrete examples

Collect at least 2 realistic user prompts that should trigger the target skill. Also collect at least 2 near-miss prompts that should not trigger it.

Use these examples to decide:

• Required workflow steps

• Output format expectations

• Edge cases to handle

• Whether deterministic scripts are needed

3. Design the skill anatomy

Create a minimal structure first:

<skill-name>/ └── SKILL.md

Add optional directories only when justified:

• scripts/ for deterministic or repeated operations

• references/ for detailed docs, schemas, and long procedures

• assets/ for templates and static resources used in outputs

4. Author SKILL.md frontmatter

Set required fields:

• name : lowercase, digits, hyphens; matches folder name

• description : what the skill does and when to use it

Common optional fields include license , compatibility , metadata , and allowed-tools . Additional frontmatter keys (for example, MCP or tooling configuration) are allowed when supported by the Agent Skills spec/validator, and may be nested under metadata when appropriate.

Description guidance:

• Include both capability and trigger cues

• Avoid vague phrases like "helps with X"

• Prefer concrete contexts and user-language synonyms

5. Author SKILL.md body

Structure the body for execution, not marketing:

• Goal and success criteria

• Step-by-step operating procedure

• Input/output expectations

• Error handling and edge cases

• Examples

• Validation checklist

Write in imperative style. Explain why non-obvious constraints matter.

6. Apply progressive disclosure

Keep SKILL.md concise. Move large or specialized content into references/ and link to it from SKILL.md .

If the skill spans multiple variants, separate variant details into dedicated reference files and keep variant-selection logic in SKILL.md .

7. Validate and harden

Run a final compatibility pass:

• Frontmatter parses as valid YAML

• name complies with spec constraints and folder match

• description is explicit about trigger contexts

• Relative file references resolve

• Optional scripts are executable and documented

• Language is agent-neutral and avoids vendor lock-in

If skills-ref is available, run:

skills-ref validate ./<skill-name>

If the skills CLI is available, verify discovery from the repo root:

npx skills list

Agent-Agnostic Rules

• Do not require a specific model vendor or proprietary UI affordance.

• Do not rely on agent-only file paths when portable paths exist.

• Do not reference unavailable tools as mandatory.

• Prefer open, portable commands and plain Markdown guidance.

Safety and integrity

• Refuse to create skills intended for malware, exploitation, data exfiltration, or unauthorized access.

• Keep behavior aligned with user intent; avoid hidden actions.

Completion criteria

A skill-creation task is complete only when all are true:

• Skill folder exists in the requested location.

• SKILL.md is valid and complete.

• Optional resources are present only if needed.

• Validation checks pass or limitations are explicitly reported.

References

• See references/spec-checklist.md for implementation rules distilled from the spec.

• See references/templates.md for copy-ready scaffolds.

• See references/research-synthesis.md for design rationale from cross-source research.