Audit and clean repositories with systematic health checks
Audits repo health across five lanes and applies only authorized fixes through the repository's own protected workflow.
Why it matters
Maintain repository health by systematically auditing artifacts, dependencies, CI/CD alignment, documentation, git hygiene, code quality, and FAF ecosystem compliance, then generating prioritized cleanup plans with optional auto-fix capabilities.
Outcomes
What it gets done
Detect test artifacts, orphaned files, and .gitignore gaps across the repository
Check dependency health, security vulnerabilities, and outdated packages
Verify CI/CD workflow consistency, Node version alignment, and action versions
Generate prioritized cleanup reports with effort estimates and auto-fix options
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-repo-maintainer | bash Overview
Repository Maintainer
A skill that audits repository health across Git hygiene, dependencies, CI, documentation, and code quality, then applies only authorized fixes through the repo's own protected merge workflow. Use when asked to maintain, clean, audit, harden, or prepare a repository for release, deferring to a more specific skill when security, database, or deployment work dominates.
What it does
Audits repository health across five independent, read-only lanes, then applies only authorized repairs and finishes through the repository's own protected workflow rather than inventing a parallel one. Before any mutation, it runs a policy gate: read root and nested AGENTS.md, contributor guidance, and release instructions; inspect the current branch, worktree, staged files, remotes, default branch, and branch protection; discover the repo's own validation/sync/merge/release commands; and preserve unrelated user work out of scope. If the repository names a mandatory maintainer skill or guarded command, it delegates to that instead of improvising - e.g. in agentic-awesome-skills it defers to antigravity-maintainer-batch-release and npm run merge:batch since main is pull-request-only, and it will not resurrect retired gates (certified-v1 baseline, benchmark, tuning-gold, transaction-fault, race, or a frozen OS/runtime matrix) as routine merge checks. The audit itself covers five lanes in parallel: Git/artifact hygiene (untracked caches/build output, tracked large or binary files, accidental secrets, stale branches, submodules, symlinks - without deleting or rewriting history); dependencies and packaging (lockfile/manifest agreement, outdated/vulnerable/duplicate/EOL packages, runtime imports misplaced in dev dependencies, clean-install behavior - treating scanner output as evidence to verify, not permission to act); CI and release health (failing or stale workflow runs, unjustifiably broad runtime matrices, unpinned actions, required checks and branch protection, documented-vs-implemented release commands); documentation and metadata drift (README, changelog, badges, contribution instructions vs current CI policy); and code-quality signals (dead code, debug logging, unsafe defaults, suppressed errors, credential exposure). For FAF projects, it also inspects .faf/.faf-dna/sync/score/MCP contracts via the project's installed FAF commands.
When to use - and when NOT to
Use it when asked to maintain, clean, audit, harden, or prepare a repository for release. Defer to a more specific security, database, deployment, or release skill when that is the dominant task instead. It never authorizes destructive cleanup, branch-policy changes, direct protected-branch pushes, merges, deployments, or releases beyond what was explicitly requested - it will never delete data, rewrite history, rotate credentials, change branch protection, or upgrade across breaking versions without explicit authorization. A request to "push to main" is read as describing the desired final state, not permission to bypass branch protection.
Inputs and outputs
git status --short --branch
git diff --stat
git diff --cached --stat
git remote -v
git log -5 --oneline
Input is the repository itself, its policy docs, and its CI/release configuration. For each finding, output is a prioritized decision record: evidence and affected paths, severity and user impact, whether it's safe to fix now, needs approval, or belongs to another workflow, and the exact validation that proves the repair - with duplicate symptoms of the same root cause merged, and optional modernization kept separate from release blockers. Repairs are the smallest coherent change set, with tests updated alongside behavior changes and the targeted failing check rerun after each repair group; the final step runs the repo's required pre-PR suite, inspects the diff for unrelated files or secrets, and opens a pull request through the repo-native merge path when the target branch is protected.
Integrations
Reads the repository's own governance surface - AGENTS.md, contributor docs, CI workflow definitions, branch protection rules, and (for FAF projects) .faf/.faf-dna contracts - and defers to whatever native validation, sync, merge, or release tooling the repository already has (e.g. npm run merge:batch in agentic-awesome-skills) rather than substituting a generic Git workflow.
Who it's for
Maintainers preparing a repository for release or general upkeep who want a systematic, evidence-based health audit with repairs applied only where authorized and always shipped through the repository's own protected merge/release path.
Source README
Repository Maintainer
Overview
Audit repository health, apply authorized repairs narrowly, and finish through the repository's own protected workflow.
When to Use
Use when the user asks to maintain, clean, audit, harden, or prepare a repository for release. Use a more specific security, database, deployment, or release skill when that is the dominant task.
Repository Policy Gate
Before mutation:
- Read root and nested
AGENTS.md, contributor guidance, maintainer docs, and release instructions. - Inspect the current branch, worktree, staged files, remotes, default branch, and effective branch protection.
- Discover repository-native validation, synchronization, merge, and release commands.
- Preserve unrelated user work and generated outputs that are not in scope.
If the repository names a mandatory maintainer skill or guarded command, delegate to it instead of inventing a parallel branch, merge, sync, or release path. In agentic-awesome-skills, use antigravity-maintainer-batch-release and npm run merge:batch; main is pull-request-only.
The routine protected checks for agentic-awesome-skills are pr-policy, pr-evidence, source-validation, and artifact-preview. The supported AAS Core preview uses targeted unit tests plus one packed Linux/Node LTS smoke path and Workbench review. Do not resurrect the retired certified-v1 baseline, benchmark, tuning-gold, transaction-fault, race, or frozen OS/runtime matrix as routine merge gates.
Usage
1. Establish the baseline
git status --short --branch
git diff --stat
git diff --cached --stat
git remote -v
git log -5 --oneline
Record the repository's required runtime versions and test commands. Use a clean temporary clone or worktree when existing user changes cannot be isolated safely.
2. Audit independent lanes
Run independent read-only checks in parallel where possible.
Artifacts and Git hygiene
- untracked caches, coverage, build output, editor files, and test leftovers;
- tracked large or binary files, accidental secrets, executable-mode drift, and ignored-file gaps;
- stale branches, detached HEAD, existing staged changes, submodules, and symlinks;
- generated files whose ownership belongs to CI or a canonical-sync workflow.
Do not delete or rewrite history during the audit.
Dependencies and packaging
- lockfile and manifest agreement;
- outdated, vulnerable, duplicate, unused, or end-of-life dependencies;
- runtime imports incorrectly placed in development dependencies;
- clean-install, package-content, and executable-entrypoint behavior.
Treat audit-tool output as evidence to verify, not automatic permission to upgrade or remove packages.
CI and release health
- failing, cancelled, skipped, or stale workflow runs;
- stale, redundant, or unjustifiably broad runtime matrices and unpinned or obsolete actions;
- required checks, branch protection, release permissions, and secret boundaries;
- mismatch between documented and implemented release commands.
Documentation and repository metadata
- README, changelog, version, examples, links, badges, credits, and support metadata;
- contribution instructions and PR templates versus current CI policy;
- generated catalog, site, or API documentation drift.
Code-quality signals
- dead code, stale implementation markers, debug logging, commented-out code, and missing tests;
- unsafe defaults, suppressed errors, credential exposure, and environment-specific paths.
For FAF projects only, also inspect declared .faf, .faf-dna, sync, score, and MCP contracts with the project's installed FAF commands.
3. Produce a prioritized decision set
For each finding report:
- evidence and affected paths;
- severity and user impact;
- whether it is safe to fix now, needs approval, or belongs to another workflow;
- exact validation that proves the repair.
Deduplicate symptoms with the same root cause. Do not mix optional modernization with release blockers.
4. Apply authorized repairs
Make the smallest coherent change set. Keep source and generated-file ownership separate, update tests with behavior changes, and rerun the targeted failing check after each repair group.
Never delete data, rewrite history, rotate credentials, change branch protection, or upgrade across breaking versions without explicit authorization.
5. Validate and publish safely
Run the repository's required pre-PR suite, then inspect the final diff for unrelated files and secrets. Commit on a topic branch and create a pull request when the target branch is protected.
Use required checks and the repository-native merge path. A user request to “push to main” describes the desired final state; it does not bypass branch protection. For releases, use the scripted release workflow and verify external publication rather than inferring success from a local tag.
Stop Condition
Finish when every in-scope finding is repaired or has one exact blocker, required validation passes, the remote integration path is verified when requested, and unrelated user work remains unchanged.
Limitations
- Maintenance findings can depend on repository-specific ownership and release policy; read local instructions before acting.
- Dependency and security scanners can produce false positives or incomplete reachability evidence.
- This skill does not authorize destructive cleanup, branch-policy changes, direct protected-branch pushes, merges, deployments, or releases beyond the user's request.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.