# AGENTS.md

Guidance for coding agents and humans working under `skills/`.

## Purpose

`skills/` stores the authoritative skill bundles for `aoa-skills`. The authored bundle owns skill meaning, especially `SKILL.md` and `techniques.yaml`. Generated catalogs, capsules, walkthroughs, and matrices may summarize a skill, but they do not replace the authored bundle.

## Read this first

Before editing a bundle in this directory, read in this order:

1. `../AGENTS.md`
2. `../docs/ARCHITECTURE.md`
3. `../docs/BRIDGE_SPEC.md`
4. `../docs/RUNTIME_PATH.md`
5. the target `skills/<skill>/SKILL.md`
6. the target `skills/<skill>/techniques.yaml`
7. any touched `checks/`, `examples/`, `references/`, or `agents/openai.yaml`
8. for live overlay skills, `../docs/OVERLAY_SPEC.md` and the matching `../docs/overlays/<family>/PROJECT_OVERLAY.md`

## Directory contract

Treat these as the canonical bundle surfaces when present:

- `SKILL.md`
- `techniques.yaml`
- optional `agents/openai.yaml`
- optional `checks/`, `examples/`, and `references/`

`SKILL.md` and `techniques.yaml` remain the canonical pair. Support artifacts should clarify, constrain, or verify the bundle. They should not silently override it.
The generated Codex-facing export lives separately under `.agents/skills/*`; edit the canonical bundle first, then regenerate the export.

Do not add per-bundle `AGENTS.md` by default. A skill bundle already carries its own contract surface, and a deeper `AGENTS.md` only makes sense when there is a real local conflict that cannot be stated cleanly in the bundle itself.

## Allowed changes

Safe, normal contributions here include:

- refining a skill's bounded workflow wording
- tightening trigger boundaries
- improving inputs, outputs, contracts, risks, anti-patterns, and verification guidance
- adding or updating support artifacts that stay public-safe and reviewable
- aligning technique traceability with upstream canon
- adding a new skill bundle when it clearly packages upstream practice into a bounded workflow

## Changes requiring extra care

Use extra caution when:

- changing a skill identifier or directory name
- changing `scope`, `status`, `summary`, `invocation_mode`, or `technique_dependencies`
- changing the relation between a bundle and its support artifacts
- removing support artifacts referenced by generated surfaces or review docs
- turning a multi-technique skill into a single-technique exception or vice versa
- changing live overlay family relationships such as `skills/atm10-*`

## Hard NO

Do not:

- put secrets, tokens, internal-only URLs, or private project runtime details here
- duplicate upstream technique doctrine that belongs in `aoa-techniques`
- widen a skill into a playbook or a downstream integration
- hide destructive or risk-heavy actions inside vague prose
- add per-bundle `AGENTS.md` as a default pattern

## Validation

When bundle sources change, run the bounded repository flow:

- `python scripts/build_catalog.py`
- `python scripts/build_agent_skills.py --repo-root .`
- `python -m unittest discover -s tests`
- `python scripts/validate_nested_agents.py`
- `python scripts/validate_skills.py`
- `python scripts/validate_agent_skills.py --repo-root .`
- `python scripts/lint_trigger_evals.py --repo-root .`
- `python scripts/build_catalog.py --check`

If only a subset of surfaces changed, still make sure the affected bundle remains bounded, public-safe, and reviewable.

## Output expectations

When reporting work in `skills/`, include:

- which skills changed
- whether bundle meaning changed or only metadata/support artifacts changed
- whether technique dependencies changed
- whether overlay relationships changed
- whether generated surfaces need to be refreshed