11 added, 0 removed. Audit A to A.
# AGENTS.md
## Repo Purpose
This repository stores reusable agent skills. Most work should be limited to
root documentation, `.agents/skills/`, and the validation scripts
under `scripts/`.
## Structure
- Skills live in `.agents/skills/<skill-name>/`
- Each skill must include `SKILL.md`
- `SKILL.md` frontmatter must contain exactly `name` and `description`; the
declared name must match the skill folder
- Supporting files such as `references/`, `scripts/`, and `assets/` are allowed
when they directly serve the skill
- `README.md` is the published skill inventory and routing guide; keep it
aligned whenever a skill is added, removed, or retitled
## Skill Taxonomy
`README.md` is the source of truth for the current skill inventory, family
routing, and composition examples. Do not duplicate that catalog here.
- Start with one principle skill for language- or discipline-specific work,
add matching domain or project overlays, and add an orthogonal workflow skill
only when the task needs that mode
- A baseline overlay is the routine default; a canonical overlay is the
stronger option for harder work in the same domain and should preserve the
baseline's core expectations
- A companion overlay adds an optional workflow without replacing its baseline
- A process overlay governs workflow or enforcement; a template overlay is a
pattern for repo-local adaptation
- A system skill builds or installs a repo-owned system instead of guiding
ordinary execution
- Keep these relationships explicit when adding or revising skills so adjacent
skills do not drift into overlapping jobs
## Working Rules
- Preserve the existing folder-based layout unless the task explicitly requires a structural change
- Keep instructions concise, specific, and grounded in files that actually exist
- Use the repo's role vocabulary consistently when naming or describing skills
- Update only the skill folder and root docs relevant to the task
- When adding or changing a skill, keep its trigger boundaries distinct from
neighboring skills and update the relevant `README.md` family and defaults
- Treat `README.md` and `AGENTS.md` as durable repo docs; do not add process or automation claims that the repository does not implement
- Prefer small, targeted edits over broad repo rewrites
- Author skills, examples, and templates independently. Keep external references
when primary documentation, specifications, research, or tool evidence supports
a concrete procedure, constraint, or maintenance decision
- Obtain explicit user agreement before incorporating third-party material that
requires additional licenses or notices; retain required notices for any such
material that remains
## Validation
There is no application build or lint workflow.
+ Keep reusable validation procedures, fixtures, expected outcomes, and checker
+ code in the repository. Never commit individual skill-maintenance run reports,
+ transcripts, logs, run-specific output snapshots, per-run hashes, or result tables, including
+ under skill `references/` or `assets/` directories.
+
+ When retaining run artifacts, use the host's task-artifact storage outside the
+ checkout, or an OS temporary directory outside it when no task storage is available.
+ Report their location in the task, not in committed files. Retain concise
+ source/version facts that support current guidance, and turn useful failures
+ into minimal reusable cases instead of shipping their run history.
+
For changes to skills, supporting files, root documentation, or validation
behavior, run:
```console
python scripts/check_skills.py
```
When `scripts/check_skills.py` or `scripts/test_check_skills.py` changes, also
run:
```console
python scripts/test_check_skills.py
```
When the metadata parser, executable skill resources, or their tests change,
also run:
```console
python scripts/test_skill_resources.py
```
Report unavailable Bash, real CMake/CTest, or PyYAML checks as skipped, not
passed. Tool discovery and optional overrides are documented in `README.md`.
When `scripts/check-skills.sh` changes, run its wrapper on a Bash-capable
system:
```console
bash scripts/check-skills.sh
```
Before finishing, verify:
- new or edited skills still live under `.agents/skills/`
- each skill folder still has `SKILL.md`
- the applicable validation commands above pass
- root docs do not claim nonexistent commands or automation
- root docs still match the current root files and published skill inventory
- examples and references point to real files
- likely skill-name references in Markdown point to published local skills
## Safety
- Do not rename or move published skill folders without explicit instruction
- Do not add generated content unless the task requires it
- Do not invent setup, CI, packaging, or release workflows that are not present in the repo
## Scope
Use this root file for the whole repository. Nested `AGENTS.md` files are not needed unless a subtree later gets a materially different workflow.