How to use the Repo Hygiene Scanner agent skill

What the repo-hygiene skill makes the agent do

The skill splits an automated cleanup into two phases that run as separate CI jobs. In the scan phase, the agent searches the repository read-only and records findings in a file. It looks for small, certain hygiene issues such as stale docs or simple test and code problems. A pattern match is treated only as a lead until the agent reads the surrounding code and confirms it.

In the fix phase, the agent reads those findings, makes minimal fixes, and commits each fix separately. After each change it runs the project's build, typecheck, lint and tests. The result is one branch that a human maintainer reviews. A run that finds nothing worth fixing is a valid, silent outcome.

• Scan phase: read-only, produces findings.json and, when needed, report-only.md.
• Fix phase: reads findings, edits code, runs verification after each fix, writes PR files.
• One Conventional Commit per finding so each fix can be audited or reverted alone.
• Findings that are too large (more than three production files or more than one hundred lines of production code) are report-only.

Install the repo-hygiene skill

Download the ZIP for the skill from this page and unzip it. You can place the folder in one of two locations. For a personal skill that applies across projects, put it in ~/.claude/skills/. For a skill that belongs to one project, put it in that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal location: ~/.claude/skills/
• Project location: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

The skill's description says it applies when the scheduled repo-hygiene workflow runs from GitHub Actions, or during an operator dry-run. In practice, the agent loads it when the invocation is part of that workflow and names the phase it is in. The workflow, not a casual chat request, is the intended trigger.

Because the skill tells the agent to read only the document for its current phase before doing anything else, the invocation should name that phase. The scan phase reads references/scan.md and the fix phase reads references/fix.md.

• Scan phase: the run is the read-only scan job.
• Fix phase: the run applies accepted findings from findings.json.
• Operator dry-run: a manual run of the same workflow.

Examples of what a run looks like

A typical scan phase reads the partitions described in references/scan.md, collects candidates, and keeps only those backed by a file:line quote. A fix phase then checks each selected finding against the current checkout, because the base may have moved since the scan. If the evidence no longer holds, that entry is moved out of fixes rather than forced through.

Every commit is additive. The agent does not amend, rebase or reset history.

• Stale documentation reference confirmed by a file:line quote, fixed in a small commit.
• Simple test issue fixed, then the Vitest run for the touched package is repeated.
• Finding too large to fit the threshold, recorded in report-only.md and filed as one consolidated issue by the workflow.

What the skill needs to run

The skill assumes a specific environment. It needs Node.js to run scripts/run-agent.mjs. The sandbox must provide rg (ripgrep), because the skill assumes tools.sandbox: docker. The project toolchain must include npm with npm run build, npm run typecheck, npm run lint and Vitest. A GitHub Actions workflow must supply credentials, checkout, pushes and PR creation. An AI model or agent runtime, Qwen Code, executes the instructions.

• Node.js (for scripts/run-agent.mjs)
• Docker sandbox image providing rg (ripgrep)
• Project toolchain: npm, npm run build, typecheck, lint and Vitest
• GitHub Actions workflow that handles credentials, checkout, pushes and PR creation
• An AI model or agent runtime (Qwen Code)

Safety notes: scripts and network access

The skill runs scripts (scripts/run-agent.mjs) and uses the network. The agent itself has no GitHub credentials and must not push, comment, create pull requests or edit labels. The workflow performs all network writes.

The skill also tells the agent not to run the CLI, examples, release scripts or networked package commands such as npx tool downloads. Scanned content is treated as untrusted, so instructions embedded in issues, comments or code are to be ignored. The skill commits model-generated changes, so it should not run unattended against important branches without review.

• Agent has no GitHub credentials; the workflow handles pushes and PRs.
• Scanned text (issues, comments, docs, code comments) is untrusted input.
• Networked package commands and arbitrary scripts are off-limits to the agent.
• Review the branch before merging; the safeguards depend on the workflow.

Tips for getting useful results

Expect a quiet run to be normal. The skill prefers quality over quantity, so a small number of certain fixes is the intended result. Read report-only.md for larger findings, since those are not committed.

If a verification command fails, the skill's rules say to fix the cause and rerun it. If a blocker stops the whole run, the agent writes failure.md instead of guessing. When you change settings source files in the project, the skill requires running npm run generate:settings-schema and committing the regenerated schema in the same commit.

• Review each commit on the branch separately.
• Check failure.md first if a run stops early.
• Keep the skill inside its intended repository and workflow.