Upkeep Repo Audit Skill
An AI audit crew for your repository: it catches docs/spec/asset drift against the code and reports findings with evidence — output-only, it never touches your files.
Skill declares output-only behavior (never modifies the target repo), explicitly requires the report be written outside the target, has a clear recovery path (disposable cache checkout re-clone), and discloses data flow (clone wei18/upkeep, npm ci, local claude CLI subprocesses). Deductions: first use auto-clones a remote repo and executes npm ci plus claude subprocesses without explicit user confirmation; no integrity pinning/checksum for ~/.cache/upkeep supply chain, so not full marks.
SKILL.md paths are clear: branches for missing/diverged checkout, idempotent npm ci guidance, and an explicit instruction to tell the user what is missing instead of failing silently. Deductions: key paths (local-audit.sh, reviewer subprocesses) are not reproduced in this static review; failure-feedback quality on abnormal input is only inferable from docs — capped at 10.
Description precisely declares triggers (audit a repo, check docs/spec/asset drift, run upkeep without CI) and non-fit (never edits). Supports en and zh-TW rubrics. Deductions: core function fully depends on a logged-in claude CLI subscription and GitHub reachability, unusable without a subscription; rubric languages exclude zh-CN — Simplified Chinese exists only at the docs layer.
MIT license, version 2.1.1, multilingual docs, design reference, and a well-explained two-surface configuration split. Deductions: package. says 0.0.0 while plugin. says 2.1.1 (version inconsistency); single-maintainer repo with no declared long-term maintenance commitment or formal update policy.
Output format is explicit (severity-grouped terminal summary plus self-contained HTML report), parity with CI and the standalone script is documented, and the never-edit positioning is a genuine differentiator. Deductions: static review cannot confirm report usability/correctness; per-run subscription cost vs. benefit is unevidenced — scored 6, below the static cap of 7.
Repository contains a real CI workflow (build + test on PR/push) and a committed test suite covering rubric completeness, workflow permissions, and action version pinning, plus a referenced self-audit run as execution evidence. Deductions: tests audit the repo's own hygiene, not audit-output quality; independent third-party reproduction of the skill's key paths is absent — static cap of 5 applies.
- First run auto-clones a remote repo and executes npm ci plus claude subprocesses; inspect the wei18/upkeep scripts manually before first use.
- Core function requires a Claude Pro/Max subscription and GitHub reachability; GitHub access from mainland China may be unstable, and there is no per-token API billing option.
- Rubric languages are en/zh-TW only — Simplified Chinese users get English audit output; docs have zh-CN but the product does not.
- The ~/.cache/upkeep cache is unpinned (no revision or checksum); executed content tracks the upstream repo.
- package. version (0.0.0) conflicts with plugin. (2.1.1); verify which governs when tracking upgrades.
What does this skill do, and when should you use it?
Upkeep is a repo-wide semantic drift auditor distributed as an Agent Skill. It dispatches focused AI reviewers in parallel to find stale docs, specs that no longer match the implementation, orphaned assets, and out-of-sync translated documentation, then reports each finding with evidence and a severity level. It is strictly output-only: it reports drift but never edits or deletes anything in the target repo. You can run it locally through your logged-in claude CLI (drawing on your Claude Pro/Max subscription, with no separate API bill), or on a schedule in CI via a reusable GitHub Actions workflow or Marketplace Action that maintains a single, upserted tracking issue.
On first use it clones the Upkeep engine to ~/.cache/upkeep and installs dependencies; then it runs the full audit pipeline (discovery → parallel reviewers → synthesis → HTML report) against the target repo. Reviewers include docs_staleness (docs drifted from code, multilingual README desync), code_hygiene (dead code, unused exports, permanently commented-out blocks), spec_flow (specs/diagrams mismatching implementation), visual_icon (outdated images and icons), duplicate_orphan (duplicate files and unreferenced assets), convention (violations of the repo's own conventions), and an i18n reviewer that is off by default. Output is a severity-grouped chat summary plus a self-contained upkeep-report.html; in CI it also upserts a single GitHub tracking issue. Reviewer enablement and severity thresholds are configured via .claude/audit.yml in the audited repo.
- Maintainers of active open-source repos who want a weekly scheduled CI run to catch README promises that no longer match code behavior
- Teams keeping multilingual docs (e.g. English plus Simplified/Traditional Chinese, Japanese, Korean READMEs) in sync, needing automatic desync detection
- Engineers inheriting an unfamiliar codebase who want a sweep for dead code, orphaned assets, and convention violations before refactoring
- Solo developers on a Claude Pro/Max plan who prefer not to pay API costs and want on-demand audits of any local repo path
- Users of Cursor, Copilot, or any of the 70+ agents supported by the skills standard, installing the same audit via npx skills add
What are this skill's strengths and limitations?
- Strictly output-only: reports drift but never edits or deletes files in the target repo
- Runs on your existing Claude Pro/Max subscription — no Anthropic API key or per-token billing
- Whole-repo semantic auditing: finds doc-code drift that linters and per-PR review bots cannot
- One pipeline, three run modes: agent skill, local script, and reusable CI workflow or Marketplace Action
- CI keeps a single upserted tracking issue (never duplicated) and produces a self-contained HTML report
- Hard dependency on a logged-in claude CLI with a Claude Pro/Max subscription — unusable without one
- An audit takes several minutes, with reviewers running as multiple parallel claude -p subprocesses, which is resource-heavy locally
- The Marketplace Action mode runs reviewers sequentially, slower than the parallel reusable workflow
- No independent test suite or third-party benchmarks are provided in the source, so audit accuracy can't be pre-verified
- In CI, the HTML report is stored as a workflow artifact and expires per the repo's retention setting
How do you install this skill?
Claude Code: run /plugin marketplace add wei18/upkeep then /plugin install upkeep@upkeep in a session. Other agents (Cursor, Copilot, etc.): run npx skills add wei18/upkeep --skill upkeep-audit. For a manual install, copy the skills/upkeep-audit/ folder into ~/.claude/skills/. Prerequisites: a logged-in claude CLI (Pro/Max subscription), Node 20+, git; CI additionally needs a repo secret named CLAUDE_CODE_OAUTH_TOKEN (generated with claude setup-token).
How do you use this skill?
After installing, just ask in any session: "Run an upkeep audit on /path/to/repo". The skill clones the engine to ~/.cache/upkeep, installs dependencies, then runs the audit (several minutes; reviewers run as parallel claude -p subprocesses — run in the background and report progress), and finally lists findings grouped by severity (high → medium → low) with file paths, plus the absolute path of upkeep-report.html. You can also skip the agent entirely: ./scripts/local-audit.sh /path/to/repo --out ~/upkeep-report.html. Note that if your working directory is inside the target repo, pass --out pointing outside it, since the audit never writes into the target repo. Local runs never create GitHub issues.
How does this skill compare with similar options?
The README draws its own comparisons: Danger checks a PR's diff against hand-written rules; Copilot/Cursor PR review looks only at diff code issues and suggests changes. Upkeep is a whole-repo semantic drift auditor that scores against the repo's own conventions, runs scheduled or on-demand rather than per PR, and never edits your code.