creating-skills

name	creating-skills
description	Create a new Agent Skill for this repository. Use this skill when asked to capture a workflow, convention, or repeated correction as a reusable skill — covers file naming, frontmatter fields, category placement, progressive disclosure, and updating the index.
license	BSD-3-Clause
metadata	{"category":"workflow"}

Creating a New Skill

Skills follow the Agent Skills open standard.

1. Choose a category

Place the skill under the most specific matching category in skills/:

Category	When to use
python/	Python tooling, packaging, dependency management
dagster/	Dagster pipelines, code locations, dg usage
infrastructure/	Pulumi IaC, secrets, Vault, Kubernetes config
containers/	Docker builds, image conventions
workflow/	Cross-cutting process conventions; meta-skills

If no category fits, create a new one and add a README.md for it.

2. Create the skill directory

The directory name becomes the skill's name. Use lowercase letters and hyphens only.

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

The name in SKILL.md frontmatter must exactly match the directory name.

3. Write SKILL.md

---
name: <skill-name>           # must match directory name; max 64 chars
description: >               # what it does AND when to use it; max 1024 chars
  <one or two sentences describing the skill and the keywords/scenarios
  that should trigger it>
license: BSD-3-Clause
metadata:
  category: <category>
---

# Skill Title

...instructions...

Description guidelines (most important field)

The description is what the agent uses to decide whether to activate the skill. Make it trigger-friendly:

• State both what the skill covers and when to use it.
• Include the specific tool names, command names, or scenario keywords an agent would encounter when the skill is relevant.
• Bad: "Conventions for X." — too vague, won't trigger reliably.
• Good: "Apply X conventions. Use this skill when doing Y or Z — covers A, B, C."

4. Apply progressive disclosure

Keep SKILL.md under ~500 lines. If the skill has deep reference material (e.g., a detailed API reference, form templates, domain-specific lookup tables), move it to a references/ subdirectory and link to it from SKILL.md:

<skill-name>/
├── SKILL.md
└── references/
    └── REFERENCE.md

In SKILL.md, reference the file by relative path:

See [detailed reference](references/REFERENCE.md) for full option listings.

5. Update the indexes

After creating the skill, update two places:

1. Category README (skills/<category>/README.md) — add a row to the table.
2. Top-level skills README (skills/README.md) — add a row to the All Skills table.

6. Validate

# Check frontmatter is valid (if skills-ref is available)
npx skills-ref validate ./skills/<category>/<skill-name>

If skills-ref is not installed, manually verify:

• name matches the directory name
• description is non-empty and under 1024 characters
• SKILL.md is the correct filename (uppercase)