Imported from v1truv1us/ai-eng-system (skills/AGENTS.md). Install upstream with npx skills add v1truv1us/ai-eng-system --skill skills. Copyright stays with the author.

Skills Repository Context

Hierarchy Level: Reusable skill definitions Parent: ../AGENTS.md — Agent coordination and skill registry Philosophy: ../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:

---
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 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