| name | creating-skills |
| description | Creates new Agent Skills (SKILL.md + optional scripts/references) that follow the Agent Skills spec. Use when the user asks to create, structure, validate, or improve an agent skill. |
Creating Skills
Create a new Agent Skills-compatible skill directory with a high-quality SKILL.md.
Quick start (new skill)
- Pick a skill name:
- 1–64 chars
- lowercase letters, numbers, hyphens only
- no leading/trailing hyphen, no consecutive
--
- Create a directory named exactly the skill name.
- Add
SKILL.md with YAML frontmatter and a short, practical body.
Minimal template:
---
name: <skill-name>
description: <what it does>. Use when <triggers / keywords / situations>.
---
# <Title Case Skill Name>
## When to use this skill
- ...
## Workflow
1. ...
## Examples
### Example 1
Input: ...
Output: ...
Authoring guidance
1) Write for discovery first (frontmatter)
The description is how agents decide to activate the skill. It should:
- Say what the skill does
- Say when to use it (include keywords users will say)
- Be third-person and specific
Good:
description: Generates descriptive git commit messages from diffs. Use when the user asks for help writing commit messages or summarizing changes for a commit.
Weak:
description: Helps with git.
2) Keep SKILL.md short; link out for details
Assume the agent is competent; include only what it needs to be correct in your environment.
When SKILL.md gets long, split content into files and link them directly from SKILL.md (avoid deep chains).
Suggested structure:
my-skill/
├── SKILL.md
├── references/
│ ├── REFERENCE.md
│ └── EXAMPLES.md
└── scripts/
├── validate.py
└── run.py
3) Prefer deterministic scripts for fragile steps
If correctness matters, bundle scripts that:
- Validate inputs
- Produce machine-checkable intermediate outputs (e.g.,
plan.json)
- Fail with actionable errors
Be explicit in instructions whether to:
- run a script (most common), or
- read a script as reference (less common)
4) Make workflows checkable
For multi-step tasks, include a checklist and validation loop:
Progress:
- [ ] Gather inputs
- [ ] Generate plan artifact
- [ ] Validate artifact
- [ ] Apply changes
- [ ] Verify outputs
5) Avoid assumptions
Don’t assume tools/packages exist. If something is required:
- name it
- show the command to install/run it
- include a fallback if possible
Review checklist
