# skills/

This directory contains portable agent skills tracked by this repo. A "skill" is a self-contained set of runnable instructions plus any
scripts, helpers, tests, and references needed to keep it reliable.

## Canonical docs

- Skill directory anatomy and path rules (canonical):
  - `../docs/runbooks/skills/SKILLS_ANATOMY_V2.md`
- SKILL.md contract format spec:
  - `../docs/runbooks/skills/SKILL_MD_FORMAT_V1.md`
- Executable entrypoint catalog:
  - `../docs/runbooks/skills/TOOLING_INDEX_V2.md`
- Create/validate/remove workflows:
  - `tools/skill-management/README.md`
- Repo-wide review checklist:
  - `../docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md`
- Skill usage recording convention:
  - `../docs/runbooks/skills/SKILL_USAGE_RECORDING_V1.md`
- Script simplification playbook:
  - `../docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md`

## Tracked skill categories

Tracked skills live under:

- `skills/workflows/`
- `skills/tools/`
- `skills/automation/`

These are the only public top-level domains. Nested folders below them are
taxonomy for behavior boundaries, not behavior changes; for example,
`skills/tools/workflow-evidence/` still contains bounded tool skills, and
`skills/automation/ci/` still contains automation skills.

Non-tracked directories are best-effort only:

- `skills/_projects/`
- `skills/.system/`

## Quick rules (summary)

- Executable entrypoints in `SKILL.md` must use absolute `$AGENT_HOME/...` paths.
- Repo-relative links are allowed for non-executable references.
- `scripts/` is for entrypoints only; shared code belongs in `lib/` or `_shared/`.
- `tests/` is required for tracked skills (smoke coverage is acceptable).
- `_shared/` directories are reusable support trees and must not contain `SKILL.md`, `scripts/`, or `tests/`.

Example entrypoint path:

```bash
$AGENT_HOME/skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh
```

See `../docs/runbooks/skills/SKILLS_ANATOMY_V2.md` for the full directory anatomy table, shared-directory rules, and examples.

## Workflow Guides

- Code review specialists workflow:
  - `workflows/code-review/code-review-specialists/`
- Planning and durable implementation artifact lifecycle:
  - `workflows/plan/README.md`
- Issue workflow families:
  - `workflows/issue/README.md`
- Browser-facing QA workflow:
  - `workflows/qa/README.md`
- HEURISTIC_SYSTEM lifecycle workflows:
  - `workflows/heuristic-system/README.md`
- Reporting workflows:
  - `workflows/reporting/daily-brief/`
  - `workflows/reporting/project-retro/`

## Naming and layout conventions

- Skill directories use kebab-case (e.g., `create-github-pr`).
- Nested area directories use kebab-case and should match the catalog taxonomy
  when the area boundary is stable enough to document.
- `_shared` is reserved for shared, non-skill content only.
- Avoid uppercase or spaces in directory names.

## Full Gate (Repository)

Run the full repository validation gate before commit:

```bash
scripts/check.sh --pre-commit
```

## Entrypoint Drift Guard (Quick Run)

When adding/removing/renaming workflow or tool entrypoints, run both checks in
the same change:

```bash
bash scripts/ci/stale-skill-scripts-audit.sh --check
scripts/check.sh --entrypoint-ownership
```
