Plug-and-play AI review skills, linting configs, and pre-commit hooks for Clean Code, Domain-Driven Design (DDD), Harness Engineering, and Agentic Workflows.
Works with GitHub Copilot, Claude Code, Cursor, OpenCode, Hermes Agent, Codex, Aider, and any other AI assistant or API.
A single, unified powerhouse combining Clean Code + DDD + Harness Engineering with ECC (Everything Claude Code / Agent Harness OS):
- 68 Specialized Subagents — architecture, review, implementation, build errors, simplification, and security (
agents/) - 286 Curated Domain Skills — cloud, database, systems, frontend, backend, security, and TDD (
skills/ecc/) - 23 Modular Language & Framework Rule Packs — TypeScript, Python, Go, Rust, Java, C#, C++, Swift, Kotlin, React, Vue, etc. (
rules/) - Zero-Latency Memory Persistence — event hooks (
SessionStart,PreCompact,SessionEnd) preserving instincts and context (hooks/) - Continuous Learning & Evolution — execution telemetry (
skill-runs.jsonl), health monitoring, and failure-driven amendments (amendify.js) - AgentShield Prompt Defense Baselines — bulletproof protection against injection, data leaks, and unsafe tool execution
- Dynamic Context Switching — surgical context profiles (
dev.md,review.md,research.md) to prevent context bloat (contexts/) - Uncle Bob's Extreme Constraints & Vibe Coding — strict discipline, YAGNI, standard library first, zero overengineering
- Matt Pocock Productivity Workflows —
/grill-me,/wait-whatviaCONTEXT.md,/handoff,/to-spec,/wayfinder,/wizard - 5-Axis Code Review & Quality Gates — Correctness, Readability, Architecture, Security, Performance
- Harness.io Enterprise CI/CD Templates — canary deployment, auto-rollback, feature flag gating, DORA metrics
- Empirical Skill Auditing & Grading —
skill-doctor(from Warp) scoring actual conversation transcripts against Efficiency & Code Quality rubrics - Standardized Skill Authoring —
update-skillenforcing action-oriented descriptions, progressive disclosure, and concise instructions - Universal CLI & Diagnostics —
clean-code-skill doctor,audit,sync,health,catalog,adapt,migrate - In-Depth Architectural Analysis — see ECC Analysis & Integration Manual
One rule set. Every tool. Every language. Complete agent operating system.
AI coding assistants are powerful — but left unchecked, they exhibit consistent failure modes observed by practitioners including Andrej Karpathy:
- Wrong assumptions, run with silently. Models pick an interpretation and implement it without flagging ambiguity or asking for clarification.
- Overengineered output. They overcomplicate code, bloat abstractions, and don't clean up the dead code they leave behind.
- Unintended side effects. They sometimes change or remove code they don't sufficiently understand, breaking behaviour that wasn't part of the task.
This skill kit exists to catch exactly these failure modes — before they reach a pull request.
skills/
shared/
rules.md ← canonical rules (edit here first)
agentic-engineering-rules.md ← spec hygiene + guardrails + AI output eval + multi-agent
code-review-quality-rules.md ← 5-axis code review rubric
extreme-constraints-rules.md ← Uncle Bob extreme constraints & vibe coding rules
mattpocock-productivity-rules.md ← productivity guardrails & workflows
harness-rules.md ← testability + observability + progressive delivery rules
husky-rules.md ← canonical commit hygiene rules
lint-report-prompt.md ← canonical lint-report prompt
release-notes-prompt.md ← canonical release notes prompt
task-summary-prompt.md ← canonical task-summary prompt
test-review-prompt.md ← test quality analyst prompt
observability-report-prompt.md ← observability analyst prompt
copilot/
_rules.instructions.md ← shared rules in Copilot format
clean-code-review.instructions.md ← Copilot code review adapter
lint-report.instructions.md ← Copilot lint report adapter
task-summary.instructions.md ← Copilot task-summary adapter
husky-enforcement.instructions.md ← Copilot commit hygiene adapter
claude/
CLAUDE.md ← thin adapter; imports @skills/shared/*.md
cursor/
.cursor/rules/
clean-code-review.mdc ← self-contained adapter with frontmatter globs
task-summary.mdc ← task-summary adapter with frontmatter globs
opencode/
AGENTS.md ← self-contained adapter
hermes/
SKILL.md ← Hermes Agent skill (YAML frontmatter + body)
codex/
.codex/instructions.md ← OpenAI Codex CLI instructions
aider/
CONVENTIONS.md ← Aider conventions file
generic/
system-prompt.txt ← raw prompt for any AI tool or API
lint-report-system-prompt.txt ← raw lint report prompt
task-summary-system-prompt.txt ← raw task-summary prompt
code-review/ ← 5-Axis Code Review skill & workflows
SKILL.md
WORKFLOWS.md
extreme-constraints/ ← Uncle Bob Extreme Constraints & Vibe Coding skill
SKILL.md
WORKFLOWS.md
productivity/ ← Matt Pocock Productivity workflows
SKILL.md
WORKFLOWS.md
harness/ ← Harness Engineering adapters
testability.md
observability.md
progressive-delivery.md
agentic-engineering.md
pipelines/ ← Harness.io pipeline templates
harness-ci.yaml ← CI: build + test + DORA metrics
harness-canary.yaml ← CD: canary deploy with auto-rollback
harness-feature-flag-gate.yaml ← CD: feature flag gated rollout
Each tool adapter is a thin wrapper: persona declaration + compact rule table + output format.
The full annotated rules live in skills/shared/rules.md.
The lint report prompt lives in skills/shared/lint-report-prompt.md.
The task summary prompt lives in skills/shared/task-summary-prompt.md.
To change a rule, update shared/rules.md and propagate to the adapters.
.
├── skills/
│ ├── shared/
│ │ ├── rules.md ← single source of truth for all rules
│ │ ├── agentic-engineering-rules.md ← spec hygiene + guardrails + AI output eval + multi-agent
│ │ ├── code-review-quality-rules.md ← 5-axis code review rubric
│ │ ├── extreme-constraints-rules.md ← Uncle Bob extreme constraints & vibe coding rules
│ │ ├── mattpocock-productivity-rules.md ← productivity guardrails & workflows
│ │ ├── harness-rules.md ← testability + observability + delivery rules
│ │ ├── husky-rules.md ← canonical commit hygiene rules
│ │ ├── lint-report-prompt.md ← canonical prompt: lint output → AI report
│ │ ├── release-notes-prompt.md ← canonical prompt: commits → release notes entry
│ │ ├── task-summary-prompt.md ← canonical prompt: session → task summary + skill recipe
│ │ ├── test-review-prompt.md ← test quality analyst prompt
│ │ └── observability-report-prompt.md ← observability analyst prompt
│ ├── copilot/
│ │ ├── _rules.instructions.md ← shared rules in Copilot format
│ │ ├── clean-code-review.instructions.md ← persona adapter
│ │ ├── lint-report.instructions.md ← lint report adapter
│ │ ├── task-summary.instructions.md ← task-summary & skill-extraction adapter
│ │ └── husky-enforcement.instructions.md ← commit hygiene adapter
│ ├── claude/
│ │ └── CLAUDE.md ← thin adapter (@file imports)
│ ├── cursor/
│ │ └── .cursor/rules/
│ │ ├── clean-code-review.mdc ← self-contained adapter
│ │ └── task-summary.mdc ← task-summary & skill-extraction adapter
│ ├── opencode/
│ │ └── AGENTS.md ← self-contained adapter
│ ├── hermes/
│ │ └── SKILL.md ← Hermes Agent skill adapter
│ ├── codex/
│ │ └── .codex/instructions.md ← OpenAI Codex CLI adapter
│ ├── aider/
│ │ └── CONVENTIONS.md ← Aider conventions adapter
│ ├── generic/
│ │ ├── system-prompt.txt ← raw code review prompt for any tool or API
│ │ ├── lint-report-system-prompt.txt ← raw lint report prompt for any AI tool or API
│ │ └── task-summary-system-prompt.txt ← raw task-summary prompt for any AI tool or API
│ ├── code-review/ ← 5-Axis Code Review skill & workflows
│ │ ├── SKILL.md
│ │ └── WORKFLOWS.md
│ ├── extreme-constraints/ ← Uncle Bob Extreme Constraints & Vibe Coding skill
│ │ ├── SKILL.md
│ │ └── WORKFLOWS.md
│ ├── productivity/ ← Matt Pocock Productivity workflows
│ │ ├── SKILL.md
│ │ └── WORKFLOWS.md
│ ├── harness/ ← Harness Engineering skill & adapters
│ │ ├── SKILL.md ← Harness Engineering canonical skill
│ │ ├── testability.md ← testability review assistant
│ │ ├── observability.md ← observability review assistant
│ │ ├── progressive-delivery.md ← feature flags + canary + circuit breakers
│ │ └── agentic-engineering.md ← spec-driven dev + guardrails + multi-agent guide
│ ├── skill-doctor/ ← Empirical skill grading engine (Warp)
│ │ ├── SKILL.md
│ │ ├── scorers/ ← Efficiency & Code Quality rubrics
│ │ ├── scripts/ ← Session collector & HTML report renderer
│ │ └── references/ ← Supported harnesses & improvement rules
│ ├── update-skill/ ← Skill authoring & refinement skill (Warp)
│ │ ├── SKILL.md
│ │ └── references/ ← Best practices & progressive disclosure
│ └── ecc/ ← 286 curated domain skills from ECC
│
├── agents/ ← 68 specialized subagents (architect, reviewer, etc.)
│
├── rules/ ← 23 modular language & framework rule packs (122 files)
│ ├── common/
│ ├── typescript/
│ ├── python/
│ ├── golang/
│ ├── rust/
│ └── ... (23 packs)
│
├── hooks/ ← zero-latency memory persistence & runtime hook configs
│ ├── hooks.json ← SessionStart, PreCompact, SessionEnd
│ └── memory-persistence/
│
├── contexts/ ← dynamic system prompt contexts (dev, review, research)
│
├── manifests/ ← ECC component and profile installation manifests
│
├── pipelines/ ← Harness.io pipeline templates
│ ├── harness-ci.yaml ← CI with DORA metrics
│ ├── harness-canary.yaml ← canary deploy with auto-rollback
│ └── harness-feature-flag-gate.yaml ← feature flag gated rollout
│
├── scripts/
│ ├── doctor.js ← workspace & harness diagnostics
│ ├── sync-ecc.js ← ECC synchronizer and asset importer
│ ├── catalog.js ← component & profile explorer
│ ├── skills-health.js ← skill evolution & telemetry dashboard
│ ├── adapt-agents.js ← cross-harness agent adapter (Gemini, Codex, Cursor)
│ ├── lint-and-report.sh ← run linting + print LLM feed instructions
│ ├── generate-release-notes.sh ← call LLM to generate a RELEASE-NOTES entry
│ └── migrate.sh ← universal project migration wizard & CLI
│
├── bin/
│ └── clean-code-skill.js ← CLI router (migrate, doctor, sync, catalog, health, adapt)
│
├── docs/
│ └── ECC-ANALYSIS-AND-INTEGRATION.md ← in-depth ECC architectural analysis and integration guide
│
├── src/
│ └── clean_code_skill_kit/ ← uvx / pip Python package
│ ├── __init__.py
│ └── cli.py ← Python entry point (calls migrate.sh)
│
├── pyproject.toml ← Python package metadata (for uvx / pip publish)
│
├── .github/
│ └── workflows/
│ ├── release-notes.yml ← auto-generate release notes on tag push
│ ├── publish-npm.yml ← publish to npm on tag push
│ └── publish-pypi.yml ← publish to PyPI on tag push
│
├── linting/
│ ├── python/
│ │ └── pyproject.toml ← Ruff + Mypy + Bandit
│ ├── typescript/
│ │ ├── .eslintrc.json ← ESLint + TypeScript + SonarJS + DDD layer rules
│ │ └── .prettierrc.json ← Prettier
│ ├── go/
│ │ └── .golangci.yml ← golangci-lint with DDD depguard rules
│ ├── java/
│ │ ├── checkstyle.xml ← Checkstyle
│ │ └── pmd-ruleset.xml ← PMD
│ ├── csharp/
│ │ └── .editorconfig ← EditorConfig + Roslyn analyser overrides
│ └── shared/
│ ├── .editorconfig ← Universal EditorConfig for all languages
│ └── .pre-commit-config.yaml ← pre-commit hooks for all languages
│
├── ai-clean-code-skill-guide.md ← background reading and design rationale
├── COMMIT-GUIDE.md ← commit message format, hooks, troubleshooting
├── LICENSE
└── README.md
If you don't want to clone the repo, run the migration wizard directly via npm or uv:
# via npm / npx (requires Node ≥ 20)
npx clean-code-skill-kit
# via uv / uvx (requires Python ≥ 3.9 and uv installed)
uvx clean-code-skill-kitBoth commands download the kit, launch the interactive wizard, copy the files you choose into your project, and then exit — nothing is permanently installed in your global environment.
Pass any flag the wizard accepts:
npx clean-code-skill-kit --tool copilot --lang typescript ../my-project --yes
uvx clean-code-skill-kit --tool claude --lang python --dry-run .Publishing the package yourself?
See.github/workflows/publish-npm.ymland.github/workflows/publish-pypi.ymlfor the automated release workflows and the one-time setup steps documented inside each file.
The fastest way to adopt the kit in a new project is the interactive migration wizard.
It asks which AI tool(s), language(s), and optional extras you want — then shows a dry-run preview before writing anything.
# Run the wizard (interactive — asks questions, previews changes, confirms before writing)
./scripts/migrate.sh
# Or via npm
npm run migrateWhat the wizard asks
| Step | Question | Default |
|---|---|---|
| 1 | Target project directory | . (current directory) |
| 2 | Which AI tool(s)? copilot / claude / cursor / opencode / hermes / codex / aider / generic / all | all |
| 3 | Copy linting configs? | yes |
| 4 | Which language(s)? python / typescript / go / java / csharp / all | all |
| 5 | Copy pre-commit hook config? | yes |
| 6 | Copy Harness Engineering files? | yes |
| 7 | Do a dry run first? | yes |
After the dry run it prints the exact command to re-run with --yes to apply the changes.
# Non-interactive (CI / scripting) — skip all questions
./scripts/migrate.sh --tool copilot --lang typescript ../my-project --yes
# Dry run only (no writes)
./scripts/migrate.sh --dry-run
npm run migrate:dry
The unified clean-code-skill CLI provides diagnostics, synchronization, and multi-harness adaptation alongside project migration:
# 1. Diagnostics: check skills, agents, rules, hooks, and linters
clean-code-skill doctor
# or via npm
npm run doctor
# 2. Sync from ECC upstream (Everything Claude Code)
clean-code-skill sync
# or verify existing assets
clean-code-skill sync --verify
# 3. Explore ECC profiles and component catalog
clean-code-skill catalog profiles
clean-code-skill catalog components --family language
# 4. Monitor skill evolution, telemetry, and health
clean-code-skill health
# 5. Adapt subagents for Google Gemini / Antigravity or OpenAI Codex
clean-code-skill adapt --target gemini
clean-code-skill adapt --target codex
# 6. Empirical skill audit (grade local Claude Code, Codex, Warp transcripts)
clean-code-skill audit --harness auto --days 30
# or
clean-code-skill skill-doctor
# 7. Migrate full Clean Code + ECC suite into any project
clean-code-skill migrate --all-ecc /path/to/my-project --yesThis repository incorporates the full capability catalog of ECC (Everything Claude Code):
| Component | Quantity / Scope | Purpose |
|---|---|---|
Specialized Subagents (agents/) |
68 Agents | Cognitive tiering: Architecture (architect, planner), Review (code-reviewer, security-reviewer), Implementation (tdd-guide), Error Resolution (build-error-resolver), Refactoring (code-simplifier), and Exploration (spec-miner). |
Curated Domain Skills (skills/ecc/) |
286 Skills | Full-stack engineering: TDD workflows, cloud architectures, database patterns, accessibility, performance tuning, and systems design. |
Modular Rule Packs (rules/) |
23 Rule Packs (122 files) | Modular coding-style, testing, security, patterns, and hooks for TypeScript, Python, Go, Rust, Java, C#, C++, Swift, Kotlin, React, Vue, etc. |
Memory Persistence Engine (hooks/) |
Zero-Latency Runtime | Event-driven state capture (SessionStart, PreCompact, SessionEnd) preserving decisions and instincts without per-prompt token overhead. |
Dynamic Execution Contexts (contexts/) |
3 System Profiles | Surgical context switches (dev.md, review.md, research.md) eliminating context clutter. |
| Prompt Defense (AgentShield) | Universal Baseline | Strict protection across all agents against prompt injection, unauthorized shell execution, and secret leaks. |
For full architectural analysis, see docs/ECC-ANALYSIS-AND-INTEGRATION.md.
If you prefer copying files directly without the wizard:
cp skills/copilot/_rules.instructions.md skills/copilot/clean-code-review.instructions.md \
skills/copilot/lint-report.instructions.md .github/
cp -r skills/shared .VS Code automatically merges all .instructions.md files in .github/ matching the applyTo glob.
Ask Copilot: "Review this file for Clean Code and DDD issues."
cp skills/claude/CLAUDE.md .
cp -r skills/shared . # so the @file references resolveClaude Code reads CLAUDE.md on startup and follows the @skills/shared/rules.md and @skills/shared/lint-report-prompt.md imports automatically.
cp -r skills/cursor/.cursor .The .mdc rule activates automatically for code files matching the declared globs.
cp skills/opencode/AGENTS.md .OpenCode reads AGENTS.md from the project root as agent context.
cp skills/hermes/SKILL.md skills/shared .hermes/skills/clean-code-ddd/Hermes Agent reads SKILL.md files from ~/.hermes/skills/ (YAML frontmatter + markdown body). Place the skill in a category folder (e.g., software-development/clean-code-ddd/) and load it with skill_view(name='clean-code-ddd').
mkdir -p .codex
cp skills/codex/.codex/instructions.md .codex/Codex automatically reads .codex/instructions.md from the project root when it starts.
cp skills/aider/CONVENTIONS.md .Aider reads CONVENTIONS.md from the project root automatically and applies the conventions to every code change.
Copy the content of skills/generic/system-prompt.txt into the system prompt field of your AI tool, API call, or agent definition.
cp linting/python/pyproject.toml .
pip install ruff mypy bandit
ruff check . && ruff format . && mypy src/ && bandit -r src/cp linting/typescript/.eslintrc.json linting/typescript/.prettierrc.json .
npm install -D eslint prettier @typescript-eslint/parser @typescript-eslint/eslint-plugin \
eslint-plugin-import eslint-plugin-unicorn eslint-plugin-sonarjs
npx eslint . --fix && npx prettier --write .cp linting/go/.golangci.yml .
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
golangci-lint run ./...Maven — add to pom.xml:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>3.3.1</version>
<configuration>
<configLocation>checkstyle.xml</configLocation>
<failsOnError>true</failsOnError>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<version>3.22.0</version>
<configuration>
<rulesets><ruleset>pmd-ruleset.xml</ruleset></rulesets>
<failOnViolation>true</failOnViolation>
</configuration>
</plugin>cp linting/java/checkstyle.xml linting/java/pmd-ruleset.xml .
mvn checkstyle:check pmd:checkcp linting/csharp/.editorconfig .
dotnet format --verify-no-changescp linting/shared/.editorconfig .Every modern editor (VS Code, JetBrains, Vim, Emacs) picks this up automatically.
cp linting/shared/.pre-commit-config.yaml .
pip install pre-commit
pre-commit install
pre-commit run --all-files # first-time checkHooks run automatically on every git commit after installation.
After running a linter you can pipe its raw output to any LLM and receive a prioritised, human-readable improvement report — no linter-code jargon, plain English explanations, and a numbered action plan.
# make executable once
chmod +x scripts/lint-and-report.sh
# run — detects python/typescript/go/java/csharp automatically
./scripts/lint-and-report.sh
# or pass language and path explicitly
./scripts/lint-and-report.sh python src/
./scripts/lint-and-report.sh typescript packages/api
./scripts/lint-and-report.sh go ./...The script runs the linter, saves raw output to lint-output.txt, then prints copy-paste commands for feeding it to each LLM.
# copy the CLAUDE.md adapter so Claude knows about the lint report skill
cp skills/claude/CLAUDE.md .
cp -r skills/shared .
# run linting, then ask Claude to analyse the output
./scripts/lint-and-report.sh
claude "Analyze the linting output in lint-output.txt and generate a human-readable report"# copy lint-report instructions so Copilot picks them up automatically
cp skills/copilot/lint-report.instructions.md .github/
# run linting
./scripts/lint-and-report.sh
# open lint-output.txt in the editor, then in Copilot Chat:
# "Analyze this lint output and generate a human-readable improvement report"# option A — CLI pipe (replace `your-llm-cli` with your tool)
cat skills/generic/lint-report-system-prompt.txt lint-output.txt | your-llm-cli
# option B — API call
# system prompt : contents of skills/generic/lint-report-system-prompt.txt
# user message : contents of lint-output.txtEvery LLM returns a structured Markdown document:
## Lint Analysis Report
Language: Python | Tool: Ruff | Files scanned: 8 | Total issues: 14 (Errors: 2, Warnings: 9, Style: 3)
### Executive Summary
Two import-order errors will break CI. Nine functions have complexity scores above
the configured threshold, making them hard to test and reason about in isolation.
### Findings by Priority
#### Must Fix — Errors (2) ← translated to plain English, mapped to Clean Code rules
#### Should Address — Warnings (9)
#### Consider — Style / Info (3)
### Top Recurring Violations ← deduplicated, counted
### Prioritised Action Plan ← numbered, ordered by impact
### Agentic Engineering
`missing-spec-before-agent` · `vague-intent` · `missing-acceptance-criteria` · `missing-edge-cases` · `spec-not-updated` · `why-not-documented` · `no-agent-persona-file` · `missing-test-baseline` · `agent-output-unvalidated` · `guardrail-too-broad` · `ai-code-not-understood` · `hallucinated-dependency` · `single-solution-accepted` · `eval-missing` · `agent-doing-everything` · `no-context-handoff` · `parallel-agents-conflict` · `missing-orchestrator` · `no-friction-log` · `skill-not-updated` · `recurring-retry-pattern`
### Clean Code Rule Mapping ← links lint codes to project rule IDs
See skills/shared/lint-report-prompt.md for the full prompt specification.
See skills/shared/rules.md for the full annotated rule set. See skills/shared/harness-rules.md for Harness Engineering rules.
Uncle Bob's Extreme Constraints (Vibe Coding) — missing-gherkin-acceptance-spec, missing-test-baseline, unexercised-branch-coverage, mutant-survival-detected, crap-complexity-breach, cyclomatic-complexity-breach, leaky-architectural-invariant, unsupervised-syntax-trust, line-by-line-micromanagement
Clean Code rules — meaningful-names, single-responsibility, minimize-duplication, avoid-deep-nesting, small-interfaces, named-constants, comment-why-not-what, clear-error-handling
DDD rules — ubiquitous-language, bounded-context-violation, aggregate-integrity-bypass, value-object-mutability, domain-logic-in-adapters, missing-acl, missing-repository-abstraction, missing-domain-event
Harness Engineering — Testability — missing-dependency-injection, no-seam-for-testing, clock-dependency, random-dependency, test-pyramid-violation, test-logic-in-production, assertion-roulette
Harness Engineering — Observability — missing-structured-logging, no-correlation-id, missing-metrics-instrumentation, silent-error-swallowing, log-without-context, missing-health-endpoint
Harness Engineering — Progressive Delivery — feature-flag-missing, config-hardcoded, missing-graceful-degradation, missing-circuit-breaker, deploy-coupled-to-release
Severity: high = fix before merge · medium = fix this sprint · low = suggestion
| Tool | Handles |
|---|---|
| EditorConfig | Indentation, line endings, encoding |
| Prettier / gofmt / dotnet format | Code formatting |
| Ruff / ESLint / golangci-lint / Checkstyle + PMD | Style, naming, complexity, magic numbers, unused code, security |
| pre-commit | Runs all of the above before every commit |
| AI skill (extreme constraints) | Uncle Bob's 6 pillars: Gherkin specs, green test baselines, mutation testing gauntlet, CRAP bounds, architectural invariants |
| AI skill (code review) | Readability, naming clarity, responsibility boundaries, DDD alignment, refactor suggestions |
| AI skill (harness — testability) | Missing DI seams, clock/random dependencies, test pyramid health, test-in-production code |
| AI skill (harness — observability) | Structured logging gaps, missing correlation IDs, unmonitored critical paths, swallowed errors |
| AI skill (harness — delivery) | Hardcoded config, missing feature flags, no circuit breaker, deploy-coupled releases |
| AI skill (lint report) | Translates raw linter output into plain English, groups by severity, maps to Clean Code rules, produces a prioritised action plan |
| AI skill (release notes) | Reads conventional commits since last tag, generates a Keep a Changelog entry, opens a PR for human review |
| AI skill (task summary) | After any AI session, produces a plain-English recap and a reusable fill-in-the-blanks prompt recipe |
After an AI coding session finishes a task, trigger this skill to capture what was done and produce a reusable prompt recipe your team can use to repeat the same type of work on any project — without rediscovering the process.
Say any of the following to your AI tool after completing a task:
"summarize this session as a skill""capture this task as a recipe""make this reusable""extract a skill from this session""document what we just did""turn this into a prompt"
The skill always produces two sections in a single Markdown document:
1 — Task Summary (≤ 1 page)
| Field | Content |
|---|---|
| Problem | One sentence: what was broken, missing, or needed |
| Approach | 3–5 bullets — key decisions and the reasoning behind them |
| Outcome | What was delivered, specific and measurable |
| Gotchas / Lessons | Edge cases hit or surprises worth noting (omitted if none) |
2 — Reusable Skill Recipe
A self-contained, fill-in-the-blanks prompt template. Every project-specific name is replaced with a <PLACEHOLDER> variable so anyone on any project can use it immediately.
## Reusable Skill Recipe: <TITLE>
> Copy this prompt into your AI tool to repeat this process on any similar project.
### Context
You are working on a project where: <DESCRIBE_PROJECT>
### Task
<DESCRIBE_TASK>
### Steps
1. …
### Output
<What the AI should produce>
### Guardrails
- …
Claude Code
cp skills/claude/CLAUDE.md .
cp -r skills/shared .GitHub Copilot
cp skills/copilot/task-summary.instructions.md .github/Any other tool (ChatGPT, API, custom agent)
Copy the content of skills/generic/task-summary-system-prompt.txt into the system prompt field of your AI tool.
Saved to skills/extracted/<YYYY-MM-DD>-<kebab-title>.md by default.
Pass a custom path in your trigger message to override, e.g. "summarize this session as a skill and save to docs/recipes/add-adapter.md".
The prompt that defines the output format and guardrails lives in skills/shared/task-summary-prompt.md.
Edit it to change the recipe structure, writing style, or placeholder naming convention.
All tool adapters reference this file — no other files need updating.
After pushing a version tag, the Generate Release Notes GitHub Actions workflow collects all conventional commits since the previous tag, sends them to an LLM, and opens a PR with the generated RELEASE-NOTES.md entry — ready for human review before merging.
git tag v0.5.0 && git push origin v0.5.0
↓
GitHub Actions: collect commits since v0.4.0
↓
LLM (Claude or GitHub Models): group by type, write human-readable bullets
↓
Insert entry into RELEASE-NOTES.md after the header
↓
Open PR: "docs(release): release notes for v0.5.0"
↓
Human reviews → merge
Option A — Claude (recommended, higher quality)
- Add
ANTHROPIC_API_KEYas a repository secret:
Settings → Secrets and variables → Actions → New repository secret - Push a tag — the workflow fires automatically.
Option B — GitHub Models (zero extra secrets)
The workflow auto-falls back to gpt-4o via GitHub Models when ANTHROPIC_API_KEY is not set.
No extra configuration needed — GitHub Actions has GITHUB_TOKEN built in.
Useful for testing or regenerating notes for a past tag:
GitHub UI → Actions → "Generate Release Notes" → Run workflow
version: 0.5.0 (optional — defaults to latest tag)
llm: claude (or github-models)
dry run: true (prints entry without opening a PR)
# Dry run — preview without modifying RELEASE-NOTES.md
ANTHROPIC_API_KEY=*** ./scripts/generate-release-notes.sh --dry-run
# Write the entry for the latest tag
ANTHROPIC_API_KEY=*** ./scripts/generate-release-notes.sh
# Specific version, GitHub Models backend (uses GITHUB_TOKEN)
GITHUB_TOKEN=*** ./scripts/generate-release-notes.sh \
--version 0.5.0 --llm github-modelsThe prompt that instructs the LLM lives in skills/shared/release-notes-prompt.md.
Edit it to change section headings, writing style, bullet length, or the commit-type → section mapping.
The workflow and the local script both read this file at runtime — no other files need updating.
| What to change | Where |
|---|---|
| Rules content or DDD checks | skills/shared/rules.md → propagate to tool adapters |
| AI output format or persona | Tool adapter in skills/<tool>/ |
| Lint report format or severity mapping | skills/shared/lint-report-prompt.md → propagate to tool adapters |
| Release notes writing style or sections | skills/shared/release-notes-prompt.md |
| Task summary structure or recipe format | skills/shared/task-summary-prompt.md → propagate to tool adapters |
| Python linting | linting/python/pyproject.toml |
| TypeScript rules or DDD import boundaries | linting/typescript/.eslintrc.json |
| Go lint rules | linting/go/.golangci.yml |
| Java complexity thresholds | linting/java/checkstyle.xml and pmd-ruleset.xml |
| C# naming and Roslyn severities | linting/csharp/.editorconfig |
| Pre-commit hook versions | linting/shared/.pre-commit-config.yaml → run pre-commit autoupdate |
- Fork the repository.
- Create a branch:
git checkout -b feature/your-change - Edit
skills/shared/rules.mdfirst, then update the affected tool adapters. - Open a pull request with a clear description of what changed and why.
Contributions welcome — new language linting configs, additional DDD checks, new AI tool adapters, or rule refinements.
MIT License
Copyright (c) 2026
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.