agentleFS
abhaylaabhayla/claude-best-practices/.claude/skills/ssot-workflow-audit/SKILL.md

ssot-workflow-audit

Skill9 starsChanged 7 months agoMITView on GitHub

Audit core/.claude/ patterns for workflow group coverage, stale seeds, and registry sync. Use when patterns are added to core/ or when reviewing workflow documentation completeness.

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 7 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Verify every core pattern has a matching entry in registry/patterns.json.

    line 92
  2. Very specific:

    Verify docs/workflows/ is in sync with config/workflow-groups.yml.

    line 119
  3. Distinctive:

    Read the Skills table from the doc

    line 133
  4. Distinctive:

    If seeds were added/removed since last generation, flag as stale

    line 135
  5. Very specific:

    If --fix argument is provided, run the auto-assignment script:

    line 141
  6. Very specific:

    If --fix is NOT provided, skip this step.

    line 149
  7. Very specific:

    MUST audit core/.claude/ patterns only — this skill does NOT audit the hub's .claude/ directory

    line 195
  8. Distinctive:

    MUST NOT modify any files in default mode — default is read-only

    line 196
  9. Distinctive:

    MUST NOT create registry entries — only report missing ones for manual action

    line 197
  10. Very specific:

    MUST run assign_workflow_groups.py only when --fix is explicitly passed

    line 198
  11. Distinctive:

    MUST distinguish FAIL (blocking) from WARN (advisory) — see severity column in each step

    line 199
  12. Distinctive:

    MUST report stale seeds (pointing to deleted patterns) as FAIL — these silently break workflow docs

    line 200
  13. Distinctive:

    MUST check both directions: patterns without groups AND groups with missing patterns

    line 201
  14. Very specific:

    MUST treat _needs-manual-review entries as WARN, not FAIL — they were auto-assigned with low confidence

    line 202

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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

SSOT Workflow Audit

Audit the hub's core/.claude/ directory to ensure every distributable pattern is assigned to a workflow group, has a registry entry, and has up-to-date workflow documentation.

Default mode is read-only. Pass --fix to auto-assign orphans via assign_workflow_groups.py. Pass --strict to treat warnings as failures.

Arguments: $ARGUMENTS


STEP 1: Inventory Core Patterns

Collect all patterns from core/.claude/ and build a complete inventory.

1a. Collect Skills

  • Glob for all core/.claude/skills/*/SKILL.md files
  • For each, read frontmatter to extract: name, version, type, description
  • Record: skill name, line count, has references/ subdirectory

1b. Collect Agents

  • Glob for all core/.claude/agents/*.md files
  • For each, read frontmatter to extract: name, model, description
  • Record: agent name (filename without .md)

1c. Collect Rules

  • Glob for all core/.claude/rules/*.md files
  • For each, read first 10 lines to extract scope declaration
  • Record: rule name (filename without .md), scope type

1d. Summary

Print inventory summary:

Core Inventory:
  Skills: X
  Agents: Y
  Rules: Z
  Total: N patterns

STEP 2: Check Workflow Group Coverage

Load config/workflow-groups.yml and verify every core pattern is assigned.

2a. Load Workflow Groups

  • Read config/workflow-groups.yml
  • Extract all seeds across all groups (skills, agents, rules)
  • Build a set of all assigned pattern names

2b. Identify Orphans

For each pattern found in Step 1, check if it appears in any workflow group's seeds.

Pattern StatusVerdictSeverity
In at least one groupOK—
In _needs-manual-review groupLOW_CONFIDENCEWARN
Not in any groupORPHANFAIL

2c. Identify Stale Seeds

For each seed name in workflow-groups.yml, verify the pattern file exists on disk:

Seed StatusVerdictSeverity
File existsOK—
File missingSTALE_SEEDFAIL

STEP 3: Check Registry Sync

Verify every core pattern has a matching entry in registry/patterns.json.

3a. Load Registry

  • Read registry/patterns.json
  • Build a set of all registered pattern names

3b. Cross-Reference

For each core pattern from Step 1:

Registry StatusVerdictSeverity
Has matching registry entryOK—
Missing from registryMISSING_REGISTRYFAIL

For each registry entry:

Pattern StatusVerdictSeverity
File exists in core/OK—
File missing from core/STALE_REGISTRYWARN

STEP 4: Check Workflow Doc Freshness

Verify docs/workflows/ is in sync with config/workflow-groups.yml.

4a. Compare Groups to Docs

For each workflow group in config/workflow-groups.yml:

Doc StatusVerdictSeverity
Matching doc exists in docs/workflows/OK—
No doc file for this groupSTALE_DOCWARN

4b. Check Doc Content

For each existing workflow doc, verify it references the current seeds:

  • Read the Skills table from the doc
  • Compare against the workflow group's current seed list
  • If seeds were added/removed since last generation, flag as stale

STEP 5: Apply Fixes (if --fix)

If --fix argument is provided, run the auto-assignment script:

PYTHONPATH=. python scripts/assign_workflow_groups.py

Then re-run Steps 2-4 to report remaining issues.

If --fix is NOT provided, skip this step.


STEP 6: Generate Report

Compile all findings into a structured report.

Report Template

## SSOT Workflow Audit Report

### Summary
| Metric | Value |
|---|---|
| Core patterns | X total (Y skills, Z agents, W rules) |
| Workflow groups | N groups |
| Assigned patterns | A of X |
| Orphans | B patterns |
| Stale seeds | C entries |
| Missing registry | D patterns |
| Stale docs | E docs |

### Violations

| # | Type | Severity | Pattern | Details |
|---|------|----------|---------|---------|
| 1 | ORPHAN | FAIL | redis-patterns | Not in any workflow group |
| 2 | STALE_SEED | FAIL | deleted-skill | Seed in testing-pipeline but file missing |
| 3 | MISSING_REGISTRY | FAIL | new-skill | No entry in registry/patterns.json |
| 4 | LOW_CONFIDENCE | WARN | mystery-skill | In _needs-manual-review group |
| 5 | STALE_DOC | WARN | hub-sync | Doc doesn't reflect current seeds |

### Verdict

| Mode | Result |
|---|---|
| Default | PASS (0 FAIL) / FAIL (N violations) |
| --strict | PASS (0 FAIL, 0 WARN) / FAIL (N violations + W warnings) |

CRITICAL RULES

  • MUST audit core/.claude/ patterns only — this skill does NOT audit the hub's .claude/ directory
  • MUST NOT modify any files in default mode — default is read-only
  • MUST NOT create registry entries — only report missing ones for manual action
  • MUST run assign_workflow_groups.py only when --fix is explicitly passed
  • MUST distinguish FAIL (blocking) from WARN (advisory) — see severity column in each step
  • MUST report stale seeds (pointing to deleted patterns) as FAIL — these silently break workflow docs
  • MUST check both directions: patterns without groups AND groups with missing patterns
  • MUST treat _needs-manual-review entries as WARN, not FAIL — they were auto-assigned with low confidence
  • In --strict mode, MUST treat all WARNs as FAILs

Download now (ZIP)

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.