Home & Overview
Relevant source files
The following files were used as context for generating this wiki page:
The claude-skills project provides a modular framework of agent-based engineering skills designed to automate and standardize software development workflows. It enforces strict production standards, architectural discipline, and predictable agent behavior through a structured set of instructions, scripts, and domain models.
Each skill functions as a discrete unit of capability that an agent invokes to perform tasks such as Code Review, Triage, or Production Implementation. The project centers on the repo-production-workflow, which orchestrates these individual skills into a governed end-to-end development cycle.
Sources: skills/write-a-skill/SKILL.md:4-8, skills/repo-production-workflow/SKILL.md:6-10
Skill System Architecture
The project organizes capabilities into "Skills." A skill consists of a mandatory SKILL.md file containing instructions and frontmatter metadata. Skills optionally include reference documents, example usage, and utility scripts for deterministic operations.
Invocation Types
Skills operate under two invocation models to balance agent autonomy with context window constraints:
| Invocation Type | Trigger Mechanism | Context Load | Usage Recommendation |
|---|---|---|---|
| Model-Invoked | Agent detects trigger in description | Permanent | When agents must act autonomously |
| User-Invoked | Human types skill name | Zero | When human judgment or specific manual firing is required |
Sources: skills/writing-great-skills/SKILL.md:12-25, skills/write-a-skill/SKILL.md:18-24
Skill Execution Flow
The following diagram illustrates how the agent processes a skill request:
This diagram shows the decision path for skill invocation and the internal hierarchy of information processing.
Sources: skills/writing-great-skills/SKILL.md:44-55, skills/writing-great-skills/SKILL.md:118-125
Core Production Workflow
The repo-production-workflow serves as the primary orchestration layer for all repository changes. It mandates a specific sequence of skill execution to ensure every change is justified, tested, and reviewed.
The 13-Step Chain
Agents must follow this sequence for behavior-changing repository work:
- Repo Context Forge: Establish repository context and base OID.
- Diagnosis: Tracing root causes for bugs via
/diagnose. - GitNexus Check: Validate architectural impact and context.
- Advisor Scope Check: Consult
/codex-advisorfor design validation. - Production Preflight: Generate before-edit proof and Behavior Maps.
- TDD RED: Execute failing attack vectors through real seams.
- Production Code Baseline: Run the quality gate to establish a clean state.
- Implementation: Smallest direct change following core standards.
- Verification: Execute local tests, linting, and quality gates.
- Delegate Code Review: Fork a reviewer agent for standards/spec review.
- Final Advisor Review: Judge the candidate and dispositions.
- Complete Workflow: Record terminal state in the SQLite event ledger.
- Delivery: Commit, push, and resolve PR signals.
Sources: skills/repo-production-workflow/SKILL.md:23-112
Workflow State Management
The workflow maintains continuity through a repository-scoped SQLite event ledger. This ledger tracks:
- Accepted transitions between phases.
- Logical evidence and findings.
- Active workflow IDs and candidate trees.
Sources: skills/repo-production-workflow/SKILL.md:12-18, skills/repo-production-workflow/SKILL.md:144-150
Domain & Architectural Governance
The project utilizes a ubiquitous language defined in CONTEXT.md files to maintain architectural integrity. Decisions are recorded in Architectural Decision Records (ADRs) to prevent re-litigation of design choices.
Domain Document Structure
Most repositories follow a single-context layout, but monorepos use a CONTEXT-MAP.md to point to per-context definitions.
The diagram outlines the file structure for managing domain knowledge and decisions.
Sources: skills/domain-modeling/SKILL.md:14-30, skills/setup-matt-pocock-skills/domain.md:19-40
Execution Planning
For multi-PR implementation or complex remediation, agents generate durable governing designs outside the Git checkout. These designs reside in <workflow-state-root>/<repo-key>/designs/<workflowId>.md.
Sources: skills/execution-planning/SKILL.md:25-35
Production Implementation Standards
All implementation follows strict "Production Code" standards to ensure minimal, direct, and duplication-averse changes.
Hard Invariants
The CLAUDE.md file defines global rules that skills cannot weaken:
- Mock Ban: Tests must cross the real production Interface/Seam. Substituted collaborators are prohibited for production proof.
- Imaginary-Risk Ban: Theoretical failures do not justify new code. Guards and abstractions require demonstrated occurrences.
- Root-Cause-First Gate: No production fix begins without reproduction and a falsifiable hypothesis.
- Contradictory-Contract Gate: Interfaces cannot promise arbitrary behavior while simultaneously forbidding specific operations.
Sources: CLAUDE.md:20-38
Quality Rubric
Agents judge changes against seven core principles:
- Minimal Code: Smallest correct change; delete obsolete lines.
- No Duplicated Behavior: Reuse existing owners.
- Direct Data Flow: Explicit and traceable I/O.
- No Fake-Green: No suppressed failures or broad catch/pass.
- Cleanup Discipline: Remove temporary artifacts and leaked state.
- Consequence Coverage: Trace adjacent consumers and callers.
- Simple Implementation: Readable and direct code.
Sources: skills/code-quality/SKILL.md:11-45
Summary
claude-skills provides a highly governed environment for agent-led engineering. By combining structured skill definitions with a mandatory 13-step production workflow and strict hard invariants, the system ensures that all repository changes are predictable, high-quality, and architecturally sound. The separation of "Steps" (actions) from "Reference" (definitions) allows agents to navigate complex codebases while adhering to a shared ubiquitous language and established architectural decisions.