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.
In this repository44 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- anthropic-multi-agent-research-system-skillSkill
- apply-selectionsSkill
- bootstrap-dogfood-projectSkill
- brainstormSkill
- branch-choiceSkill
- cc-adoption-scoutSkill
- claude-guardianSkill
- continueSkill
- end-sessionSkill
- executing-plansSkill
- five-advisorsSkill
- get-work-doneSkill
- git-branch-lifecycleSkill
- githubSkill
- grill-meSkill
- hook-transcript-fixture-testSkill
- instagramSkill
- linkedinSkill
- modern-data-pipeline-diagramSkill
- pattern-qualitySkill
- platform-event-live-probeSkill
- plugin-lifecycleSkill
- promote-to-coreSkill
- prompt-auto-enhanceSkill
- provision-reportSkill
- redditSkill
- review-new-claude-featuresSkill
- save-sessionSkill
- scan-discovery-reportSkill
- scan-repoSkill
- scan-urlSkill
- self-improveSkill
- skill-evaluatorSkill
- skill-masterSkill
- start-sessionSkill
- synthesize-hubSkill
- synthesize-projectSkill
- twitter-xSkill
- verify-effect-at-destinationSkill
- workflow-doc-reviewerSkill
- writing-plansSkill
- writing-skillsSkill
- youtube-transcriptSkill
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
- Very specific: line 92
Verify every core pattern has a matching entry in registry/patterns.json.
- Very specific: line 119
Verify docs/workflows/ is in sync with config/workflow-groups.yml.
- Distinctive: line 133
Read the Skills table from the doc
- Distinctive: line 135
If seeds were added/removed since last generation, flag as stale
- Very specific: line 141
If --fix argument is provided, run the auto-assignment script:
- Very specific: line 149
If --fix is NOT provided, skip this step.
- Very specific: line 195
MUST audit core/.claude/ patterns only — this skill does NOT audit the hub's .claude/ directory
- Distinctive: line 196
MUST NOT modify any files in default mode — default is read-only
- Distinctive: line 197
MUST NOT create registry entries — only report missing ones for manual action
- Very specific: line 198
MUST run assign_workflow_groups.py only when --fix is explicitly passed
- Distinctive: line 199
MUST distinguish FAIL (blocking) from WARN (advisory) — see severity column in each step
- Distinctive: line 200
MUST report stale seeds (pointing to deleted patterns) as FAIL — these silently break workflow docs
- Distinctive: line 201
MUST check both directions: patterns without groups AND groups with missing patterns
- Very specific: line 202
MUST treat _needs-manual-review entries as WARN, not FAIL — they were auto-assigned with low confidence
≈ “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.
Files
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.mdfiles - 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/*.mdfiles - For each, read frontmatter to extract: name, model, description
- Record: agent name (filename without .md)
1c. Collect Rules
- Glob for all
core/.claude/rules/*.mdfiles - 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 patternsSTEP 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 Status | Verdict | Severity |
| In at least one group | OK | — |
In _needs-manual-review group | LOW_CONFIDENCE | WARN |
| Not in any group | ORPHAN | FAIL |
2c. Identify Stale Seeds
For each seed name in workflow-groups.yml, verify the pattern file exists on disk:
| Seed Status | Verdict | Severity |
| File exists | OK | — |
| File missing | STALE_SEED | FAIL |
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 Status | Verdict | Severity |
| Has matching registry entry | OK | — |
| Missing from registry | MISSING_REGISTRY | FAIL |
For each registry entry:
| Pattern Status | Verdict | Severity |
| File exists in core/ | OK | — |
| File missing from core/ | STALE_REGISTRY | WARN |
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 Status | Verdict | Severity |
Matching doc exists in docs/workflows/ | OK | — |
| No doc file for this group | STALE_DOC | WARN |
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.pyThen 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.pyonly when--fixis 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-reviewentries as WARN, not FAIL — they were auto-assigned with low confidence - In
--strictmode, MUST treat all WARNs as FAILs
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
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.

