The /creating-agent-skills Skill

What it does

creating-agent-skills is the packaging skill for this collection: how to add or change a SKILL.md so agents load it reliably and CI accepts it.

It covers directory layout, frontmatter fields, naming rules, categories, the tagline-vs-description split, and the validate/index workflow. It does not invent the domain expertise inside a skill — that’s your job (or another research/planning session).

When to reach for it

• Adding a brand-new skill to ravid7000/skills
• Editing an existing skill’s frontmatter or structure
• Reviewing a PR that adds or changes a skill

Do not use for:

• Writing the subject-matter content of a skill (the “what experts know”)
• Installing or consuming skills in an agent tool — see the collection README
• Editing unrelated Markdown elsewhere in the repo

Prerequisites

A checkout of the skills repository with npm install available so you can run npm run validate and npm run index.

How it works

1. Pick a name — Lowercase, numbers, single hyphens; verb-first / gerund style. Directory name and name: must match.
2. Create skills/<name>/ — Flat namespace; no nested categories.
3. Copy the template — From references/skill-template.md into SKILL.md.
4. Write frontmatter — Required: name, description, metadata.category, metadata.tagline.
5. Write the body — Keep it lean; put heavy material in references/. Must include When to Use and Do not use for.
6. Validate — npm run validate.
7. Regenerate the index — npm run index updates the README skills table; commit it.
8. Open a PR — CI runs the same checks.

Frontmatter that matters

Field	Reader	Shape
description	Agent deciding whether to load the skill	Long, trigger-shaped, starts with “Use when…”
metadata.tagline	Human scanning README / npm	One plain sentence, ≤120 chars
metadata.category	Repo taxonomy	One of: meta, research, workflow, diagnostics, maintenance

Categories are repo policy enforced by validate — not part of the open agentskills spec. Growing the vocabulary should be a visible PR decision.

What you get

A skill directory that passes validate, appears in the generated README index, and loads in agents that follow the Agent Skills layout.

Field reference and review checklist live in the source skill.

Common questions

Can I nest skills in category folders?
No. Flat under skills/ only. Category is metadata, not a path.

Why both tagline and description?
Agents need triggers; humans need a scannable sentence. Mixing them produces either an unreadable README or a skill agents fail to select.

Does this teach me what to put in the skill body?
Only the packaging. For research into a domain, use finder; for shaping a large new skill, start with plan-with-me.

It’s working if

• name matches the directory and naming rules
• description is trigger-shaped; tagline is a plain one-liner
• Category is from the allowed list
• npm run validate and npm run index succeed
• Heavy detail lives in references/, not a 500+ line SKILL.md

Where it fits

Meta layer for the whole collection. Use it whenever the set of skills changes shape. The skills you author then show up on this site’s Skills hub once the portfolio catalog is updated to match.