Marwan-Ahmed-devMarwan-Ahmed-dev/vibecode-pro-max/.claude/skills/vc-audit/SKILL.md

vc:audit

Skill0 starsChanged 3 months agoMITView on GitHub

Audit the kit — context routing, shared-skill discoverability, Claude/Codex wiring, harness health, plan inventory. Use when context docs, skill surfaces, agent definitions, README.md, protocol files, or plan artifacts move, split, or drift.

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Treat .claude/agents/ as canonical for agent definitions.
line 84
Very specific:
Treat .claude/skills/ as canonical.
line 116
Very specific:
When updating agents, mirror Claude markdown and Codex TOML surfaces together via build-codex-toml.mjs
line 117
Very specific:
Do not move large context files without updating process/context/all-context.md
line 118
Distinctive:
Do not delete compatibility wrappers unless no current reference points to them
line 119
Distinctive:
Treat validator warnings as audit findings unless the user asks for a strict cleanup
line 120
Distinctive:
Prefer validator-backed routing truth over adding more soft prose
line 121
Distinctive:
Keep context groups durable-domain based, not one group per temporary feature
line 122

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Audit

Single skill for all kit-audit work. Three modes:

--context (default) — context routing, skill discoverability, Claude/Codex wiring
--vc — harness health (agent parity, skill registry, README sync, protocol wiring, seed consistency)
--plans — active plan inventory and staleness

Default (no args): run all three modes

node .claude/skills/vc-audit/scripts/validate-context-discovery.mjs
node .claude/skills/vc-audit/scripts/validate-skill-routing.mjs
node .claude/skills/vc-audit/scripts/validate-skill-cross-refs.mjs
node .claude/skills/vc-audit/scripts/validate-skill-dependencies.mjs
node .claude/skills/vc-audit/scripts/validate-confusable-skills.mjs
node .claude/skills/vc-audit/scripts/generate-skills-catalog.mjs --check
node .claude/skills/vc-audit/scripts/validate-agent-parity.mjs
node .claude/skills/vc-audit/scripts/validate-skills.mjs
node .claude/skills/vc-audit/scripts/validate-guide-sync.mjs
node .claude/skills/vc-audit/scripts/validate-protocol-wiring.mjs
node .claude/skills/vc-audit/scripts/validate-seeds.mjs
node .claude/skills/vc-audit/scripts/validate-plan-inventory.mjs

Mode: --context

Context routing + skill discoverability + Claude/Codex wiring.

# 1. Context discovery
node .claude/skills/vc-audit/scripts/validate-context-discovery.mjs

# 2. Skill routing coverage
node .claude/skills/vc-audit/scripts/validate-skill-routing.mjs

# 3. Skill cross-references
node .claude/skills/vc-audit/scripts/validate-skill-cross-refs.mjs

# 4. Skill dependencies + confusables
node .claude/skills/vc-audit/scripts/validate-skill-dependencies.mjs
node .claude/skills/vc-audit/scripts/validate-confusable-skills.mjs

# 5. Regenerate or check the machine-readable skill catalog
node .claude/skills/vc-audit/scripts/generate-skills-catalog.mjs --write
node .claude/skills/vc-audit/scripts/generate-skills-catalog.mjs --check

See references/audit-context.md for the full context audit process. Treat references/skill-routing-policy.json as the explicit allowlist for intentionally non-routed shared skills. process/context/generated-skills-catalog.json is the machine-readable catalog owned by this mode.

Mode: --vc

Harness health: agent parity, skill registry, README sync, protocol wiring, seed consistency, plus the Codex mirror build step.

# 1. Claude/Codex agent parity
node .claude/skills/vc-audit/scripts/validate-agent-parity.mjs

# 2. Skill registry consistency
node .claude/skills/vc-audit/scripts/validate-skills.mjs

# 3. README sync
node .claude/skills/vc-audit/scripts/validate-guide-sync.mjs

# 4. Protocol wiring
node .claude/skills/vc-audit/scripts/validate-protocol-wiring.mjs

# 5. Seed file consistency
node .claude/skills/vc-audit/scripts/validate-seeds.mjs

# 6. Regenerate the Codex mirror (call this after editing any agent source)
node .claude/skills/vc-audit/scripts/build-codex-toml.mjs
node .claude/skills/vc-audit/scripts/validate-agent-parity.mjs  # re-run to confirm

Treat .claude/agents/ as canonical for agent definitions; .codex/agents/ mirrors them. The validate-agent-parity.mjs check rejects any hand-edited TOML — all TOML must carry the # Generated by build-codex-toml.mjs header. Use build-codex-toml.mjs before commits that touch agent sources.

Mode: --plans

Active plan inventory and staleness.

# 1. Plan inventory validator
node .claude/skills/vc-audit/scripts/validate-plan-inventory.mjs

# 2. Inventory plans in process/general-plans/active/ and process/features/*/active/
# 3. Scan sibling reports/ and references/ for artifacts tied to plans classified Completed/Obsolete
# 4. Cross-check each plan against the codebase (file existence + targeted rg)
# 5. Classify: Completed | Partially Done | Obsolete | Stale | Active | Reference
# 6. Move clearly completed/obsolete plans to completed/
# 7. Ask before deleting anything
# 8. Re-run validate-plan-inventory.mjs after moving or editing plan files

See references/audit-plans.md for the full plan-audit process.

When to Use

Situation	Mode
Context docs or skill surfaces move/split/drift	`--context`
Agent definitions, README.md, or protocol files change	`--vc`
Reconciling accumulated active-plan drift	`--plans`
Periodic health check	(no args — run all)

Rules

Treat .claude/skills/ as canonical; .agents/skills/ is the Codex discovery symlink
When updating agents, mirror Claude markdown and Codex TOML surfaces together via build-codex-toml.mjs
Do not move large context files without updating process/context/all-context.md
Do not delete compatibility wrappers unless no current reference points to them
Treat validator warnings as audit findings unless the user asks for a strict cleanup
Prefer validator-backed routing truth over adding more soft prose
Keep context groups durable-domain based, not one group per temporary feature

End every response with the subagent status block:

**Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
**Summary:** [1-2 sentence summary]
**Mode run:** --context | --vc | --plans | all
**Files modified:** [comma-separated list]
**Concerns/Blockers:** [if applicable]

Download now (ZIP)

In this repository51 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- vc:kitSkill
- vc:auditSkill
- vc:autoresearchSkill
- vc:chrome-devtoolsSkill
- vc:context-engineeringSkill
- vc:debugSkill
- vc:docs-seekerSkill
- vc:generate-contextSkill
- vc:generate-planSkill
- vc:mcp-managementSkill
- vc:merge-worktreeSkill
- vc:previewSkill
- vc:problem-solvingSkill
- vc:publishSkill
- vc:repomixSkill
- vc:scoutSkill
- vc:securitySkill
- vc:sequential-thinkingSkill
- vc:setupSkill
- vc:stress-testSkill
- vc:tech-graphSkill
- vc:updateSkill
- vc:watzupSkill
- vc:web-testingSkill
- vc:xiaSkill
- vc:kitSkill
- vc:autoresearchSkill
- vc:chrome-devtoolsSkill
- vc:context-engineeringSkill
- vc:debugSkill
- vc:docs-seekerSkill
- vc:generate-contextSkill
- vc:generate-planSkill
- vc:mcp-managementSkill
- vc:merge-worktreeSkill
- vc:previewSkill
- vc:problem-solvingSkill
- vc:publishSkill
- vc:repomixSkill
- vc:scoutSkill
- vc:securitySkill
- vc:sequential-thinkingSkill
- vc:setupSkill
- vc:stress-testSkill
- vc:tech-graphSkill
- vc:updateSkill
- vc:watzupSkill
- vc:web-testingSkill
- vc:xiaSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free