authoring-adept-skillslisted

# Authoring a good adept skill A skill is a directory `<root>/skills/<id>/` with one `SKILL.md` (YAML frontmatter + markdown body) and optional sidecars. `adept` renders it into every enabled harness, so write it **once, well, and harness-neutral**. ## Canonical SKILL.md format ```markdown --- id: pr-review # ^[a-z0-9](?:[a-z0-9-]{0,48}[a-z0-9])?$ — matches the directory name description: Use before opening a PR. Tests, security, performance. # <= 280 chars activation: agent # always | globs | agent | manual globs: [] # REQUIRED when activation: globs (e.g. ["**/*.go"]) allowed-tools: [Read, Grep] # carried into Claude Code targets: [] # empty = all enabled harnesses tags: [review, quality] --- # PR Review Checklist - [ ] Tests added or updated - [ ] No secrets in the diff ``` Validated against `pkg/adeptschema/skill.schema.json` on every load — `adept sync` fails loudly on a malformed skill, so let it catch your mistakes. ## Pick activation deliberately — this is the whole game | activation | Fires when | Use for | |---|---|---| | `agent` | The model decides from the **description** | Most skills. Procedures, checklists, how-tos. | | `globs` | A matching file is in context | Language/path-specific rules (`**/*.go`, `**/*.tsx`). | | `always` | Every request | Rare. Project-wide invariants only — costs budget on every turn. | | `manual` | Only when explicitly invoked | Heavy or destructive procedures