whobat Skill Name
One-paragraph overview: what this skill achieves and the core approach (e.g. "the bundled script collects X as JSON; the agent writes the narrative").
How to run (script-backed skills)
SCRIPT = this skill's scripts/Your-Script.ps1. Document the exact invocation,
a table of the parameters that matter, and 2-3 copy-paste examples.
Output contract
What the script prints (JSON shape, exit codes), and what goes to a file vs stdout.
What you (the agent) do with the result
- Numbered, imperative steps.
- Lead with what matters; don't recite everything.
- Fail loud: name every coverage gap, skipped section, or unverified assumption.
Gotchas
REQUIRED (validator-enforced; may live here or in REFERENCE.md). The real, mechanism-level pitfalls of this domain — the traps that produce confident-but-wrong conclusions. For each: the trap → why it happens → the correct check/fix. Cover measurement traps (a tool/command that reports a misleading value), errors that point at the wrong cause, environment foot-guns, and known misattributions. Keep it honest and specific — a few verifiable gotchas beat a padded list. Add to it when a real run uncovers a new pitfall. Committed gotchas must be generic — no company-specific data.
Environment-specific gotchas (local). At the start of a run, read gotchas.local.md
in this skill's folder if it exists — it holds traps learned in this environment (real
server/DB names, local quirks). When you discover a new environment-specific pitfall,
append it there, not to this file. gotchas.local.md is gitignored and is preserved
across skill updates, so the skill gets more useful every time it's used here.
Verification
REQUIRED (validator-enforced; may live here or in REFERENCE.md). Document two things:
- Before changes — how to verify correctness/preconditions first: a baseline, a repro, a health-check, or (for read-only skills) how to confirm ground truth and coverage before recommending anything. Never propose a change without a before-check.
- Output — how to verify the result afterward: re-run the check, confirm the expected effect landed, and fail loud if it can't be confirmed. Never report "done" unverified.
Errors
Known failure modes → what to tell the user.