agentleFS
abhaylaabhayla/claude-best-practices/.claude/skills/workflow-doc-reviewer/SKILL.md

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.

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
  1. Very specific:

    Read $ARGUMENTS and determine mode:

    line 37
  2. Very specific:

    If --generate is present → Generate mode (Step 3)

    line 39
  3. Very specific:

    If --review is present → Review mode (Step 4)

    line 40
  4. Distinctive:

    Run the generator in dry-run to collect data without writing:

    line 47
  5. Very specific:

    If --workflow <name> was specified, filter output to that workflow only.

    line 60
  6. Distinctive:

    STOP here — do not write any files.

    line 62
  7. Very specific:

    If --dry-run was also specified:

    line 74
  8. Very specific:

    If --workflow <name> was specified:

    line 80
  9. Distinctive:

    Ask user if they want to add manual annotations to any workflow doc

    line 90
  10. Very specific:

    If yes: read the doc, get annotation text, append below <!-- MANUAL ANNOTATIONS --> marker

    line 91
  11. Very specific:

    Default mode MUST be read-only — NEVER write files without explicit --generate

    line 143
  12. Distinctive:

    MUST NOT edit auto-generated sections of workflow docs — only annotations below the marker

    line 144
  13. Distinctive:

    MUST run from repository root with PYTHONPATH=.

    line 145

≈ “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.

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

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

ModeFlagWrites Files?Purpose
Status(default)NoShow workflow summary, orphans, and cross-workflow connections
Generate--generateYesRegenerate docs/workflows/*.md from reference graph
Review--reviewNoDeep 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 --generate is present → Generate mode (Step 3)
  • If --review is 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-run

Then present:

  1. Workflow summary table — name, skill count, agent count, rule count for each group
  2. Orphan patterns — patterns not in any workflow group (suggest where they belong)
  3. Cross-workflow connections — which workflows feed into which others
  4. Stale check — compare docs/workflows/*.md timestamps 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.py

If --dry-run was also specified:

PYTHONPATH=. python scripts/generate_workflow_docs.py --dry-run

If --workflow <name> was specified:

PYTHONPATH=. python scripts/generate_workflow_docs.py --workflow <name>

After generation:

  1. Show summary of created/updated files
  2. Report orphan patterns and suggest workflow group assignments
  3. 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

Run validation:

PYTHONPATH=. python scripts/workflow_quality_gate_validate_patterns.py

STEP 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.md or .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.yml is the source of truth for grouping — MUST NOT hardcode groups
  • scripts/generate_workflow_docs.py is the standalone script — this skill wraps it, does not replace it
  • Orphan patterns MUST be reported with suggested group assignments

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.