---
name: <kebab-case-name-matching-this-folder>
description: <what it does AND when to trigger — specific and a little pushy so it doesn't under-fire; one or two sentences>
---

# <Skill title>

<One line: what this skill lets the agent do.>

## When to use

- <concrete trigger context>
- <another trigger context>

## How it works

<Imperative steps. Explain the *why* behind each one. Keep it lean; push long
reference detail into references/ and point to it from here.>

## Output

<What the skill produces, and the output format if it matters.>

## Safety / boundaries

- <what this skill must not do>

# What makes a good skill

A condensed authoring recipe (distilled from the skill-creator approach). Read this before writing a new skill's body.

## Anatomy

```
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter — name, description (both required)
│   └── Markdown body — the instructions
└── optional bundled resources:
    ├── scripts/    — executable helpers for deterministic / repetitive work
    ├── references/ — docs loaded into context only when needed
    └── assets/     — files used in the output (templates, icons, fonts)
```

## Progressive disclosure (the core idea)

A skill loads in three levels — keep the cheap things small so the expensive ones load only when needed:

1. **name + description** — always in context (~100 words). The triggering surface.
2. **SKILL.md body** — loaded when the skill triggers. Keep it lean (well under ~500 lines).
3. **Bundled resources** — loaded on demand; scripts can run without being read into context.

If the body grows past ~500 lines, move detail into `references/*.md` and point to it with a one-line "read X when you need Y."

## The description field (most important)

The description is the *only* thing the agent sees when deciding whether to use the skill. So:

- Say **what it does** AND **when to trigger** — concrete phrases, contexts, file types.
- Be a little **pushy** — models tend to *under*-trigger skills. e.g. "Use this whenever the user mentions X, Y, or Z, even if they don't say the word 'skill'."
- One or two sentences. Put everything else in the body.

## Writing the body

- **Imperative voice.** "Read the manifest", not "the skill reads the manifest."
- **Explain the why.** A capable model follows reasoning better than rigid rules. Prefer "do X because Y" over "ALWAYS DO X." If you catch yourself writing ALL-CAPS MUSTs, reframe and explain instead.
- **Output formats** — when the output shape matters, give an explicit template.
- **Examples** — a couple of Input → Output examples beat a paragraph of prose.
- **General, not overfit.** Write for the whole class of cases, not the single example in front of you.

## Bundle a script when work repeats

If every use of the skill would re-derive the same helper (parse the same file, build the same artifact), write it once into `scripts/` and have the skill call it. Deterministic, faster, consistent.

## Lack of surprise (safety)

A skill's contents must match its stated intent. No malware, no exploit code, nothing that does something the description doesn't admit. If a described skill would surprise the user in what it actually does, don't write it that way.

#!/usr/bin/env python3
"""Validate that a skill folder is well-formed before it is proposed for review.

Domain-general: this knows nothing about SWMM or any specific domain. It checks
the structural contract every skill must satisfy — a SKILL.md carrying a name +
description in its frontmatter and a non-empty body — so a freshly drafted skill
can be auto-checked before a human is asked to approve it.

Usage:
    python3 validate_skill.py path/to/skill-dir

Exit code 0 = valid, 1 = problems (printed to stderr), 2 = bad invocation.
"""
from __future__ import annotations

import re
import sys
from pathlib import Path

_NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
_MIN_DESCRIPTION_CHARS = 40
_BLOCK_SCALAR_RE = re.compile(r"^[>|][+-]?$")


def _parse_frontmatter(text):
    """Split leading ``---`` YAML frontmatter from the body.

    Returns ``(front, body)`` where ``front`` is a dict of the simple
    ``key: value`` scalars (all a skill header needs), or ``(None, text)`` if
    there is no frontmatter block. Values written as YAML block scalars
    (``key: >`` / ``key: |`` with indented continuation lines) are joined so
    a multi-line description measures its real length, and indented
    continuation lines are never misread as keys.
    """
    lines = text.splitlines()
    if not lines or lines[0].strip() != "---":
        return None, text
    for i in range(1, len(lines)):
        if lines[i].strip() == "---":
            front = {}
            j = 1
            while j < i:
                raw = lines[j]
                if raw.startswith((" ", "\t")) or ":" not in raw:
                    j += 1
                    continue
                key, _, val = raw.partition(":")
                val = val.strip()
                if _BLOCK_SCALAR_RE.match(val):
                    # Folded (>) joins with spaces; literal (|) keeps newlines.
                    sep = " " if val.startswith(">") else "\n"
                    parts = []
                    j += 1
                    while j < i and (
                        lines[j].startswith((" ", "\t")) or not lines[j].strip()
                    ):
                        parts.append(lines[j].strip())
                        j += 1
                    front[key.strip()] = sep.join(p for p in parts if p)
                    continue
                front[key.strip()] = val
                j += 1
            return front, "\n".join(lines[i + 1:])
    return None, text


def validate(skill_dir):
    """Check one skill folder. Return a list of human-readable problems (empty = OK)."""
    skill_dir = Path(skill_dir)
    skill_md = skill_dir / "SKILL.md"
    if not skill_md.is_file():
        return [f"no SKILL.md found in {skill_dir}"]

    front, body = _parse_frontmatter(skill_md.read_text(encoding="utf-8", errors="ignore"))
    if front is None:
        return ["SKILL.md has no '---' YAML frontmatter block at the top"]

    problems = []

    name = front.get("name", "")
    if not name:
        problems.append("frontmatter is missing a 'name'")
    else:
        if not _NAME_RE.match(name):
            problems.append(f"name '{name}' is not kebab-case (lowercase words joined by '-')")
        if name != skill_dir.name:
            problems.append(f"name '{name}' does not match the folder name '{skill_dir.name}'")

    description = front.get("description", "")
    if not description:
        problems.append(
            "frontmatter is missing a 'description' (this is how the agent decides when to use the skill)"
        )
    elif len(description) < _MIN_DESCRIPTION_CHARS:
        problems.append(
            f"description is only {len(description)} chars; write a fuller one that says "
            "what it does AND when to use it"
        )

    if not body.strip():
        problems.append("SKILL.md has an empty body below the frontmatter")

    return problems


def main(argv):
    if len(argv) != 2:
        print("usage: python3 validate_skill.py path/to/skill-dir", file=sys.stderr)
        return 2
    problems = validate(argv[1])
    if problems:
        print(f"INVALID: {argv[1]}", file=sys.stderr)
        for p in problems:
            print(f"  - {p}", file=sys.stderr)
        return 1
    print(f"PASS: {argv[1]} is a well-formed skill")
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv))

"""Contract tests for validate_skill.py — a well-formed skill passes, malformed ones fail."""
import importlib.util
from pathlib import Path

_SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "validate_skill.py"
_spec = importlib.util.spec_from_file_location("validate_skill", _SCRIPT)
validate_skill = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(validate_skill)


def _write_skill(parent, name="demo-skill", description=None, body="# Demo\n\nDoes a thing."):
    if description is None:
        description = "A demo skill that does a thing and triggers when the user asks for that thing."
    skill = parent / name
    skill.mkdir(parents=True, exist_ok=True)
    front = ["---", f"name: {name}"]
    if description is not False:
        front.append(f"description: {description}")
    front.append("---")
    (skill / "SKILL.md").write_text("\n".join(front) + "\n\n" + body, encoding="utf-8")
    return skill


def test_wellformed_skill_passes(tmp_path):
    skill = _write_skill(tmp_path)
    assert validate_skill.validate(skill) == []


def test_missing_skill_md_fails(tmp_path):
    empty = tmp_path / "empty-skill"
    empty.mkdir()
    problems = validate_skill.validate(empty)
    assert problems and "no SKILL.md" in problems[0]


def test_missing_description_fails(tmp_path):
    skill = _write_skill(tmp_path, description=False)  # omit the description line
    assert any("description" in p for p in validate_skill.validate(skill))


def test_name_must_match_folder(tmp_path):
    skill = _write_skill(tmp_path, name="demo-skill")
    renamed = skill.parent / "other-folder"
    skill.rename(renamed)
    assert any("match the folder name" in p for p in validate_skill.validate(renamed))


def test_real_skill_author_passes():
    # dogfood: the skill-author skill itself must be well-formed
    skill_author = _SCRIPT.resolve().parent.parent
    assert validate_skill.validate(skill_author) == []


def test_folded_block_description_measures_full_length(tmp_path):
    """``description: >`` continuation lines count toward the length check.

    Regression: the parser used to read the block-scalar marker itself
    (1 char) as the value, failing legitimate multi-line descriptions.
    """
    skill = tmp_path / "demo-skill"
    skill.mkdir()
    (skill / "SKILL.md").write_text(
        "---\n"
        "name: demo-skill\n"
        "description: >\n"
        "  A folded multi-line description that says what the skill does\n"
        "  and when the agent should reach for it.\n"
        "---\n\n# Demo\n\nBody.\n",
        encoding="utf-8",
    )
    assert validate_skill.validate(skill) == []


def test_literal_block_description_measures_full_length(tmp_path):
    skill = tmp_path / "demo-skill"
    skill.mkdir()
    (skill / "SKILL.md").write_text(
        "---\n"
        "name: demo-skill\n"
        "description: |-\n"
        "  A literal multi-line description that says what the skill does\n"
        "  and when the agent should reach for it.\n"
        "---\n\n# Demo\n\nBody.\n",
        encoding="utf-8",
    )
    assert validate_skill.validate(skill) == []