workflow-doc-reviewer
Skill9 starsChanged 7 months agoMITView on GitHub
Review workflow health, audit cross-references, and regenerate workflow documentation in docs/workflows/. Default mode is read-only (status + gaps). Use --generate to write docs, --review for deep audit.
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
- ssot-workflow-auditSkill
- start-sessionSkill
- synthesize-hubSkill
- synthesize-projectSkill
- twitter-xSkill
- verify-effect-at-destinationSkill
- writing-plansSkill
- writing-skillsSkill
- youtube-transcriptSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 5 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Read $ARGUMENTS and determine mode:
- Very specific: line 39
If --generate is present → Generate mode (Step 3)
- Very specific: line 40
If --review is present → Review mode (Step 4)
- Distinctive: line 47
Run the generator in dry-run to collect data without writing:
- Very specific: line 60
If --workflow <name> was specified, filter output to that workflow only.
- Distinctive: line 62
STOP here — do not write any files.
- Very specific: line 74
If --dry-run was also specified:
- Very specific: line 80
If --workflow <name> was specified:
- Distinctive: line 90
Ask user if they want to add manual annotations to any workflow doc
- Very specific: line 91
If yes: read the doc, get annotation text, append below <!-- MANUAL ANNOTATIONS --> marker
- Very specific: line 143
Default mode MUST be read-only — NEVER write files without explicit --generate
- Distinctive: line 144
MUST NOT edit auto-generated sections of workflow docs — only annotations below the marker
- Distinctive: line 145
MUST run from repository root with PYTHONPATH=.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Workflow Doc Reviewer
Single entry point for workflow documentation and health review. Traces how skills, agents, and rules interconnect across development, testing, debugging, learning, and authoring workflows.
Arguments: $ARGUMENTS
Modes
| Mode | Flag | Writes Files? | Purpose |
| Status | (default) | No | Show workflow summary, orphans, and cross-workflow connections |
| Generate | --generate | Yes | Regenerate docs/workflows/*.md from reference graph |
| Review | --review | No | Deep audit: broken refs, stale seeds, missing bidirectional edges |
Additional flags:
--dry-run— preview generate output without writing--workflow <name>— focus on a single workflow group
STEP 1: Parse Mode
Read $ARGUMENTS and determine mode:
- If
--generateis present → Generate mode (Step 3) - If
--reviewis present → Review mode (Step 4) - Otherwise → Status mode (Step 2)
STEP 2: Status Mode (default, read-only)
Run the generator in dry-run to collect data without writing:
PYTHONPATH=. python scripts/generate_workflow_docs.py --dry-runThen present:
- Workflow summary table — name, skill count, agent count, rule count for each group
- Orphan patterns — patterns not in any workflow group (suggest where they belong)
- Cross-workflow connections — which workflows feed into which others
- Stale check — compare
docs/workflows/*.mdtimestamps against latest skill/agent/rule modification times
If --workflow <name> was specified, filter output to that workflow only.
STOP here — do not write any files.
STEP 3: Generate Mode (writes files)
Run the generator:
PYTHONPATH=. python scripts/generate_workflow_docs.pyIf --dry-run was also specified:
PYTHONPATH=. python scripts/generate_workflow_docs.py --dry-runIf --workflow <name> was specified:
PYTHONPATH=. python scripts/generate_workflow_docs.py --workflow <name>After generation:
- Show summary of created/updated files
- Report orphan patterns and suggest workflow group assignments
- Ask user if they want to add manual annotations to any workflow doc
- If yes: read the doc, get annotation text, append below
<!-- MANUAL ANNOTATIONS -->marker - Annotations survive future regeneration runs
- If yes: read the doc, get annotation text, append below
Run validation:
PYTHONPATH=. python scripts/workflow_quality_gate_validate_patterns.pySTEP 4: Review Mode (read-only deep audit)
Perform a comprehensive workflow health audit. Read config/workflow-groups.yml
and all pattern files. Check for issues using the checklist in
references/audit-checklist.md.
4A: Seed Existence Check
For every seed pattern listed in config/workflow-groups.yml, verify the
corresponding file exists:
- Skills:
core/.claude/skills/{name}/SKILL.mdor.claude/skills/{name}/SKILL.md - Agents:
core/.claude/agents/{name}.md - Rules:
core/.claude/rules/{name}.md
Report any seeds pointing to non-existent patterns as BROKEN SEEDS.
4B: Cross-Reference Integrity
For each pattern in a workflow group, read its body and extract all Skill(),
Agent(), and /skill-name references. Check that every referenced pattern
exists. Report broken references.
4C: Bidirectional Edge Audit
For each edge A→B in the reference graph, check if B also references A. One-way edges are not necessarily bugs, but flag them for review — they may indicate incomplete integration.
4D: Workflow Coverage Report
Count total patterns vs. assigned patterns. Report:
- Coverage percentage (assigned / total)
- Top 10 most-connected patterns (highest in-degree + out-degree)
- Isolated patterns (0 edges — may be stubs or standalone utilities)
Present findings as a structured report. Do NOT write any files.
CRITICAL RULES
- Default mode MUST be read-only — NEVER write files without explicit
--generate - MUST NOT edit auto-generated sections of workflow docs — only annotations below the marker
- MUST run from repository root with PYTHONPATH=.
config/workflow-groups.ymlis the source of truth for grouping — MUST NOT hardcode groupsscripts/generate_workflow_docs.pyis the standalone script — this skill wraps it, does not replace it- Orphan patterns MUST be reported with suggested group assignments
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.

