Home / repo-engineering
Repo Engineering
Repository engineering skills: verify documentation claims against the working tree, run an audit whose every finding cites a resolvable path:line, write AGENTS.md and CLAUDE.md that hold only what code cannot say, check a README's first screen, rank untested functions and entry points, write onboarding guides only from cited facts, plan restructures from the import graph, mine ADRs from git history, run offline hygiene checks with SARIF, and check release notes against the commits between two tags.
Install
In Claude Code, add the marketplace and install the plugin:
/plugin marketplace add basitalisandhu/claude-skills
/plugin install repo-engineering@claude-skillsOr copy the skill files into ~/.claude/skills/ from a clone:
git clone https://github.com/basitalisandhu/claude-skills
cd claude-skills
python3 install.py --user --only repo-engineeringSkills
| Skill | What it does | Scripts |
|---|---|---|
| adr-miner | Recover architecture decisions that were made but never written down, by mining git history (commit messages with decision phrases such as switch to, replace, adopt, drop, migrate, deprecate, in favour of), configuration changes (a dependency swapped in a manifest, a Dockerfile base image changed, CI files added or removed) and TODO or NOTE comments that carry a rationale, then drafting MADR stubs with status proposed that cite the commit SHA for every line; a second script lints an existing docs/adr folder for numbering gaps, duplicate numbers, missing or unknown status and broken superseded links. | yes |
| agent-context-writer | Write or refresh AGENTS.md and CLAUDE.md so they hold only what an agent cannot learn by reading the code (commands that are in no manifest, conventions, forbidden actions, environment setup, where to look first), and lint the result with a bundled script that flags lines restating package.json scripts, pyproject scripts, Makefile or justfile targets, dependency lists, pinned runtime versions or directory trees, paths that do not exist, generic advice, and length over a budget. | yes |
| cited-codebase-audit | Audit a whole repository against a fixed checklist (structure, entry points, dependency hygiene, dead code candidates, test coverage of entry points, secrets and config handling, CI health) where every finding must cite a path:line with a quoted snippet, and a bundled validator rejects any finding whose citation does not resolve. | yes |
| docs-truth-check | Verify that a repository's README, docs/, AGENTS.md and CLAUDE.md still match the code, using a deterministic script that checks file paths, relative links, CLI flags and their documented defaults, environment variables, function and class names, config keys, npm and make targets, and version strings against the working tree. | yes |
| readme-who-what-why | Check whether a README answers six questions in its first screen (what it is in one sentence, who it is for, why it exists or what it replaces, how to install in one block, how to run one example, where to ask) with a bundled script that scores presence and position of each, flags hype words, and prints the gaps as a to-do list; then fix the gaps with verified text. | yes |
| release-notes-verifier | Check a release's notes against what actually changed, with a bundled script that reads the commits between two tags (and, only when asked, pull request titles through a read-only gh call) and compares them with the CHANGELOG section or a release notes file, flagging notes that match no commit, commits with no note (chores excluded by a configurable pattern), manifest versions that disagree with the tag, and missing compare or reference links. | yes |
| repo-hygiene-bundle | Run one offline hygiene pass over a repository with a bundled script and report each finding with a severity, as a table, JSON or SARIF, with an exit code for CI. | yes |
| repo-onboarding-guide | Write an onboarding guide for a repository (how to run it, how to test it, where things live, which services it needs, who owns what) only from facts a bundled script extracted with a path:line citation each, then lint the guide so every sentence that names a command, path, variable, service or owner matches a fact, and run docs-truth-check on the result. | yes |
| restructure-planner | Plan a repository restructure (split a package or a monorepo, merge packages, fix module boundaries) from the real import graph instead of a guess, using a bundled script that reads Python imports with ast and JS or TS imports and requires with regex, then reports the most coupled files, import cycles, files importing from many packages and god modules, and proposes a move plan as a table (file, from, to, reason, blast radius as the number of importers) with the exact git mv commands, which it prints and never runs. | yes |
| untested-entry-points | Find public functions, classes and CLI entry points that no test mentions, using a bundled script that parses Python with ast and JS or TS exports with regex, maps each unit to the test files that reference it by name, ranks the untested ones (entry points first, then by size and fan-in), and writes characterisation test stubs in the project's framework (pytest, unittest, jest, vitest, node:test). | yes |
Plugin README
Ten skills for repository audits, documentation and release checks, each with a tested standard-library Python script. Install with /plugin marketplace add basitalisandhu/repo-engineering-skills and then /plugin install repo-engineering@repo-engineering-skills. Skills appear as /repo-engineering:<skill>, and Claude also invokes them on its own when a request matches a skill's description.
| Skill | Script | Use it to |
|---|---|---|
docs-truth-check | skills/docs-truth-check/scripts/docs_truth_check.py | verify README, docs/, AGENTS.md and CLAUDE.md claims against the working tree; exit 1 on drift |
cited-codebase-audit | skills/cited-codebase-audit/scripts/repo_facts.py, skills/cited-codebase-audit/scripts/audit_validate.py | audit a repository from a deterministic inventory, and reject findings whose path:line citations do not resolve |
agent-context-writer | skills/agent-context-writer/scripts/context_lint.py | write AGENTS.md or CLAUDE.md with only what code cannot say, and lint out what a parser can see |
readme-who-what-why | skills/readme-who-what-why/scripts/readme_check.py | score whether a README's first screen says what, who, why, install, example and where to ask |
untested-entry-points | skills/untested-entry-points/scripts/test_gaps.py | rank untested public functions and entry points and write characterisation test stubs |
repo-onboarding-guide | skills/repo-onboarding-guide/scripts/onboarding_facts.py, skills/repo-onboarding-guide/scripts/onboarding_lint.py | extract cited facts, write an onboarding guide only from them, and flag sentences no fact supports |
restructure-planner | skills/restructure-planner/scripts/restructure_plan.py | build the import graph, find cycles, coupling and god modules, and print a move plan with git mv commands (never run) |
adr-miner | skills/adr-miner/scripts/adr_mine.py, skills/adr-miner/scripts/adr_lint.py | draft MADR stubs from decision commits, config changes and rationale comments, and lint an ADR folder |
repo-hygiene-bundle | skills/repo-hygiene-bundle/scripts/hygiene.py | offline hygiene findings with severities, as a table, JSON or SARIF, with a CI exit code |
release-notes-verifier | skills/release-notes-verifier/scripts/release_notes_verify.py | compare release notes with the commits between two tags, and version fields with the tag |
Requirements: Python 3.11 or newer on PATH as python3, and git for adr-miner and release-notes-verifier. No network access (except release_notes_verify.py --gh), no third-party packages.