# Skills Repository Context

**Hierarchy Level:** Reusable skill definitions
**Parent:** [../AGENTS.md](../AGENTS.md) — Agent coordination and skill registry
**Philosophy:** [../CLAUDE.md](../CLAUDE.md) — Compounding Engineering philosophy

Modular, reusable skill definitions that support the agents defined in the parent AGENTS.md.

## Project Overview

Mostly flat skill definitions for Claude Code and OpenCode, with a small number of namespaced subdirectories such as `ai-eng/` and `workflow/`. Each skill is self-contained in its own directory with a `SKILL.md` file and optional supporting files.

## Directory Structure

The catalog holds 76 core skills. Rather than enumerating them here (the list drifts), use the filesystem as the source of truth:

```
skills/
├── <skill-name>/            # One directory per skill, flat by default
│   ├── SKILL.md             # Required: frontmatter (name, description) + instructions
│   ├── evals/evals.json     # Proof cases (required for model-invoked skills)
│   └── references/          # Optional supporting docs, templates, patterns
├── ai-eng/                  # Namespace container (no SKILL.md of its own)
│   └── simplify/
├── pstack/                  # Namespace container (poteto-stack imports)
│   └── arena/, automate-me/, how/, poteto-mode/, reflect/, ...
├── workflow/                # Namespace container
│   └── ralph-wiggum/
├── gtm/                     # Vendored GTM catalog (opt-in, gitignored source)
├── AGENTS.md                # This file
└── DELETED_SKILLS.md        # Audit log of retired skills
```

Rules: one skill per directory; `SKILL.md` frontmatter `name` must match the directory name; namespace containers group related skills and never carry their own `SKILL.md`.

## Skill Format

Each skill follows the Claude Code/OpenCode skill format:

```markdown
---
name: skill-name
description: Brief description for semantic matching. Include trigger words.
---

# Skill Name

[Skill instructions and content]
```

## Adding a Skill (policy)

Frontier models have absorbed most trending skills, so extra instructions fight the model's training, inflate routing cost, and add noise. A skill is added only when ALL of these hold:

1. **It earns its place.** It provides at least one of: (A) **private context** the model couldn't know (company templates, internal data, personal taste, exact proprietary steps), (B) **custom tool access** (wires a tool/MCP the model can't invoke otherwise), or (C) a **specific custom workflow** (an exact sequence of steps a command/agent depends on). Restating public knowledge (OWASP, SOLID, MEDDICC, ADRs, "write clean code") is not enough — plain prompting already produces that.
2. **It doesn't overlap an existing skill.** Search `skills/` first. Extend an existing skill rather than add a near-duplicate; if redundant, document the survivor in `skills/DELETED_SKILLS.md`.
3. **It carries proof.** Add an `evals/evals.json` (prompt + expected_output + assertions). For `model-invoked` skills this is enforced by `scripts/check-skill-evals.ts` in CI; a skill without evals cannot be `model-invoked`.
4. **It's correctly categorized.** Set `metadata.category: user-invoked` (slash/manual only — costs nothing at startup) unless the skill genuinely must auto-load, in which case `model-invoked`. Bias toward `user-invoked`. Run `sync-skill-taxonomy` to verify invariants.

Before adding, run the deletion test: on a typical task, would the model's output be noticeably worse without this skill? If not, don't add it. See `reports/skills-audit-2026-07.md` for the framework and prior retirements.

The catalog is kept honest by the **autoreview skill-health loop** (`bun run skill:health`): a weekly cron plus a PostToolUse invocation logger that re-audits redundancy, staleness, eval gaps, and unused skills, self-heals safe issues, and flags the rest. See `reports/skill-health-loop.md`.

## Self-Improving Loop (policy)

Skills improve through a controlled feedback loop, never unrestricted self-editing:

1. **Observe**: `hooks/session-outcome-recorder.sh` appends outcome-labeled runs to `skills/<name>/run-history.jsonl` (gitignored).
2. **Diagnose**: `bun run skill:improve` clusters failure signatures; a learning requires ≥3 occurrences or 1 high-severity incident.
3. **Learn**: qualifying learnings are auto-appended to `skills/<name>/learnings.md` (committed, terse, 90-day expiry). This is the only file automation may write inside a skill directory.
4. **Propose**: the `skill-improver` agent turns evidence into SKILL.md patch candidates under `reports/skill-proposals/` (gitignored).
5. **Gate**: candidates pass `scripts/check-skill-safety.ts` plus a held-out shadow eval (`scripts/skill-candidate-eval.ts`); promotion requires ≥ +3pp holdout pass rate and ≤10% runtime regression.
6. **Promote/rollback**: promotion lands only via human-merged PR (`chore/skill-improve`); prior versions are kept immutable in `skills/<name>/versions/v<N>/` and restored by `scripts/rollback-skill.ts`.

**Automation-immutable**: SKILL.md YAML frontmatter and any section titled `## Safety`, `## Scope`, or `## Boundaries` may never be edited by automation. Vendored `skills/gtm/` is exempt from the whole loop.

## Selected Skills

The table below highlights the most commonly invoked skills in this repository. Additional namespaced and alignment skills are also available under `skills/`.

| Skill | Description | Invoked By |
|-------|-------------|------------|
| `prompt-refinement` | Transform prompts into structured TCRO format | `/ai-eng/research`, `/ai-eng/plan`, `/ai-eng/work`, `/ai-eng/spec` |
| `comprehensive-research` | Multi-phase research orchestration | `/ai-eng/research` |
| `code-review-and-quality` | Multi-axis review before merge | `/ai-eng/code-review` |
| `code-simplification` | Behavior-preserving simplification | Alignment with `/ai-eng/simplify` workflow |
| `debugging-and-error-recovery` | Root-cause debugging and recovery | Failure analysis and break-fix work |
| `graph-rag` | Relationship-aware retrieval over graph structure | Multi-hop and entity-heavy retrieval tasks |
| `incremental-implementation` | Thin vertical slice implementation | Multi-file feature and refactor work |
| `multimodal-corpus-ingestion` | Normalize mixed corpora before analysis or retrieval | Code + docs + PDFs + diagrams + transcripts |
| `text-cleanup` | Remove AI-generated verbosity and slop | Text cleanup and editing workflows |
| `coolify-deploy` | Coolify deployment best practices | `/ai-eng/deploy` |
| `git-worktree` | Git worktree workflow management | `/ai-eng/work` (large features) |
| `plugin-dev` | Plugin development for Claude Code/OpenCode | `/ai-eng/create-*` commands |

## Skill Loading Mechanism

Skills are loaded via the native `skill` tool in Claude Code and OpenCode:

1. **Discovery**: At startup, skill names and descriptions are indexed
2. **Activation**: When a request matches a skill's description, the agent invokes `skill({ name: "skill-name" })`
3. **Loading**: Full `SKILL.md` content is loaded into context
4. **Execution**: Agent follows the skill's instructions

## Code Style

- Each skill has dedicated `SKILL.md` with YAML frontmatter
- Use descriptive `description` field with trigger words for semantic matching
- Keep skill descriptions concise and actionable
- Include practical examples and usage patterns
- Supporting files go in subdirectories (e.g., `templates/`, `patterns/`, `references/`)

## Integration Notes

- Skills integrate with parent AGENTS.md coordination system
- Must maintain compatibility with command implementations
- Each skill should be self-contained and reusable
- Skills are synced to `.claude/skills/` and `.opencode/skill/` during build