audit-workspace

name

audit-workspace

description

Use this skill to audit, check, or evaluate the current workspace's AI configuration against best practices. This is the RIGHT tool whenever someone wants to know if their CLAUDE.md is good, if their workspace setup is correct, what configuration is missing, or whether the project follows AI tooling best practices. Covers Claude Code and GitHub Copilot config files. Produces a scored compliance report with findings and next steps. NOT for creating config files — only for reviewing what exists.

Audit Workspace

Audit AI configuration files in a workspace against best practices. Covers: instructions, skills, agents.

Context Detection

Run scripts/detect-context.sh <workspace-path> to get one of: cc, copilot, dual, none.

Load references based on context:

• Always: all references/common/ files
• cc or dual: also load all references/cc/ files
• copilot or dual: also load all references/copilot/ files
• cc or copilot (not dual): also load references/dual/criteria-interop.md
• none: only common criteria apply (I-01 will fire as critical)

Inventory

Run scripts/list-workspace-files.sh <workspace-path> to get a table of CATEGORY|STATUS|PATH lines.

Group results by category: instructions, skills, agents.

Audit Process

For each file with status present in the inventory:

1. Read the file content.
2. Count lines with scripts/count-lines.sh <file>.
3. For skills and agents, validate frontmatter with scripts/check-yaml-frontmatter.sh <file> [required-fields].
4. Apply every criterion from the loaded references matching the file's category. Each criterion documents its own check logic, patterns, thresholds, and messages.

For absent files, check whether their absence triggers a criterion (e.g., I-01 if no instruction file exists at all).

Collect findings as: {criterion_id, severity, file, message, action}.

Report Format

Output the report in this exact structure:

AUDIT REPORT — <project-name> — <date>
DETECTED CONTEXT: <Claude Code | Copilot | Dual | None>

GLOBAL SCORE: <score>/100

INVENTORY
  <status>  <path>
  ...

FINDINGS
  🔴 CRITICAL (<count>)
    [<id>] <file> — <message>
    → <corrective action>

  🟡 WARNING (<count>)
    [<id>] <file> — <message>
    → <corrective action>

  🔵 INFO (<count>)
    [<id>] <file> — <message>
    → <corrective action>

NEXT STEPS
  1. <highest priority action>
  2. ...
  3. ...

Omit empty severity sections. Limit NEXT STEPS to 3–5 items, ordered by impact.

If context is dual, add an INTEROPERABILITY section between FINDINGS and NEXT STEPS with cross-tool recommendations.

Scoring

score = max(0, 100 - (critical_count * 10) - (warning_count * 3) - (info_count * 1))

Gotchas

• Self-audit trap: Never audit files under the skill's own directory. If the workspace contains this skill, exclude it.
• Cross-context bleed: Never apply cc-only criteria to a copilot-only context or vice versa. The context detection output is the single source of truth.
• Absent ≠ finding: A missing .github/copilot-instructions.md in a cc-only project is not a finding (except via I-09 as info).
• Score floor: The score cannot go below 0.
• One finding per violation: If a file triggers I-02 (too long), count it once even if it's 500 lines over the threshold.

References

Path	Content	When to load
references/common/criteria-instructions.md	I-01 to I-08	Always
references/common/criteria-skills.md	S-01 to S-10	Always
references/common/criteria-agents.md	A-01 to A-07	Always
references/cc/criteria-instructions-cc.md	I-10, I-13	cc or dual
references/cc/criteria-skills-cc.md	S-11	cc or dual
references/cc/criteria-agents-cc.md	A-08, A-10	cc or dual
references/copilot/criteria-instructions-cop.md	I-11, I-12	copilot or dual
references/copilot/criteria-agents-cop.md	A-06, A-09	copilot or dual
references/dual/criteria-interop.md	I-09	cc-only or copilot-only

Scripts

Script	Purpose
scripts/detect-context.sh [path]	Detect cc/copilot/dual/none
scripts/list-workspace-files.sh [path]	Inventory AI config files
scripts/count-lines.sh <file>	Count lines in a file
scripts/check-yaml-frontmatter.sh <file> [fields]	Validate YAML frontmatter