skill-authoring git:20260629.ee6fb37A

Immutable. This exact content is served forever at /api/v1/blob/9c437bf617f8cdac.

---
description: Conventions for writing or editing a SKILL.md skill package.
globs: **/SKILL.md
---

# Authoring a SKILL.md

Every skill is a self-contained package documented by its `SKILL.md`.

## Frontmatter

YAML frontmatter is required on every `SKILL.md`:

```yaml
---
name: kebab-case-skill-name        # matches the folder name
description: >                      # ≤ ~60 tokens — surfaced in manifests & routers
  One or two sentences on what the skill does and when to use it.
metadata:
  version: 1.0.0
  tags: [tag-one, tag-two]
---
```

The `description` is consumed by `cli/skills.json`, `registry.json`, and `.gemini/skills-index.json` — keep it tight (≤ ~60 tokens) and action-oriented. Generative skills open with a brief **Clarify-First** alignment step before producing output.

## Progressive disclosure

Keep the top of `SKILL.md` lean (Tier-1: purpose, when-to-use, the core workflow). Push depth into `references/` and load it on demand. Don't inline a 2,000-line knowledge base into the workflow.

## Structure

- `scripts/` — Python CLI tools, **standard library only, no ML/LLM calls** (see the python-tools rule).
- `references/` — expert knowledge bases the workflow links to.
- `assets/` — user-facing templates.

## After any add / rename / remove

Regenerate the machine-readable surfaces so nothing drifts:

```bash
python scripts/build_manifest.py   # rewrites cli/skills.json, registry.json, .gemini/skills-index.json
```

If you change a domain's skill count, also update `.claude-plugin/marketplace.json` (and that domain's `.claude-plugin/plugin.json`) plus the prose configs (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`, `.goosehints`).