Skill reviewer enhancements

AGENTS.md

@@ -36,6 +36,8 @@ workflow-name/
     phase-name.md       # Implementation for each phase
   commands/
     phase-name.md       # Thin wrappers that invoke controller or SKILL.md
+  scripts/              # Optional — deterministic operations invoked by skills
+  prompts/              # Optional — prompt templates for sub-agent delegation
 ```
 
 **Key architectural principles:**
@@ -91,7 +93,7 @@ Workflows write outputs to `.artifacts/{workflow-name}/{context}/`:
 - **bugfix**: `.artifacts/bugfix/{issue-number}/` (root-cause.md, reproduction.md, etc.)
 - **code-review**: `.artifacts/code-review/{branch}/` (00-reviewer-profile.md, 01-change-summary.md, code-review-{NNN}.md, review-response-{NNN}.md, review-metadata.json, decisions-{NNN}.json)
 - **triage**: `.artifacts/triage/{project}/` (issues.json, analyzed.json, report.html)
-- **skill-reviewer**: `.artifacts/skill-reviewer/{skill-name}/` (review.md)
+- **skill-reviewer**: `.artifacts/skill-reviewer/{skill-name}/` (file-hashes.json, skill-map.md, review.md)
 - **cve-fix**: `.artifacts/cve-fix/{context}/` (context.md, patch-log.md, validation-results.md, pr-description.md, backport-log.md, close-report.md)
 - **prd**: `.artifacts/prd/{issue-number}/` (01-requirements.md, 02-clarifications.md, 03-prd.md, 04-pr-description.md, 05-review-responses.md)
 - **design**: `.artifacts/design/{issue-number}/` (01-context.md, 02-research.md, 03-design.md, 04-epics.md, 05-stories/epic-{N}-{slug}.md, 05-stories/epic-{N}/story-{NN}-{slug}.md, 06-coverage.md, 07-pr-description.md, 08-review-responses.md, publish-metadata.json, sync-manifest.json)
@@ -202,6 +204,8 @@ For detailed workflow development guidelines (structure, file conventions, testi
 - Single-phase workflow (no controller)
 - Read-only review (fixing findings is separate from review phase)
 - Must read all files in target skill before forming opinions
+- Runs `scripts/pre-review-checks.py` for automated structural, frontmatter, reference, and sequencing checks before LLM evaluation
+- For large skills (15+ files), delegates initial reading to an Explore sub-agent using `prompts/analyze-skill.md`, which produces a skill map at `.artifacts/skill-reviewer/{skill-name}/skill-map.md`
 
 ### docs-writer
 
@@ -343,6 +347,8 @@ ai-workflows/
 ├── kcs/
 ├── prd/
 ├── skill-reviewer/
+│   ├── prompts/
+│   └── scripts/
 ├── triage/
 ├── install.sh                 # Installer with auto-discovery
 ├── uninstall.sh              # Removal script

CONTRIBUTING.md

@@ -95,3 +95,25 @@ This ensures symlinks resolve paths correctly regardless of where the workflow i
 - Keep `SKILL.md` under 30 lines. Use progressive disclosure (`guidelines.md`, `README.md`) for details.
 - Use consistent terminology within a workflow. Pick one term and stick with it.
 - Don't duplicate content between `SKILL.md`, `guidelines.md`, and `controller.md` (when present). Each file has a distinct role.
+
+## Scripts
+
+Some workflows include a `scripts/` directory for scripts that offload deterministic work from the LLM — validation, data transformation, file discovery, or any operation better handled by code than by prompt. The `scripts/` directory is optional and follows these conventions:
+
+- Scripts are invoked by the workflow's skill files, not by users directly
+- Scripts must work when the workflow is installed via symlink (`scripts/` under the workflow root)
+- Exit codes: `exit 0` = informational (findings reported but workflow continues), `exit 1` = halt (workflow should stop and surface the failure). Scripts that only report findings (like pre-review checks) should always exit 0.
+- Use Python 3 or bash — whichever fits the task
+
+Currently, only `skill-reviewer/scripts/` uses this pattern.
+
+## Prompts
+
+Some workflows include a `prompts/` directory for prompt templates given to sub-agents that perform delegated work — structured reading, analysis, or exploration that benefits from a fresh context window. The `prompts/` directory is optional and follows these conventions:
+
+- Prompt templates are self-contained — the sub-agent receives only the prompt, not the caller's context
+- Templates use `{placeholder}` syntax for values the caller fills in before spawning the sub-agent
+- Prompts must work when the workflow is installed via symlink (`prompts/` under the workflow root)
+- Prompts instruct the sub-agent to write output to `.artifacts/`, not to return it in conversation
+
+Currently, only `skill-reviewer/prompts/` uses this pattern.

skill-reviewer/README.md

@@ -17,6 +17,10 @@ This workflow provides a skeptical, structured review of any AI skill directory:
 skill-reviewer/
 ├── commands/
 │   └── review.md
+├── prompts/
+│   └── analyze-skill.md
+├── scripts/
+│   └── pre-review-checks.py
 ├── skills/
 │   └── review.md
 ├── guidelines.md
@@ -26,7 +30,7 @@ skill-reviewer/
 
 ### How Commands and Skills Work Together
 
-The **command** (`commands/review.md`) is a thin wrapper that routes directly to the **review skill** (`skills/review.md`), which contains the full review process. No controller is needed — this is a single-phase workflow.
+The **command** (`commands/review.md`) is a thin wrapper that routes directly to the **review skill** (`skills/review.md`), which contains the full review process. The **prompts** directory contains `analyze-skill.md`, a prompt template given to an Explore sub-agent when reviewing large skills (15+ files) to produce a structured skill map before evaluation. The **scripts** directory contains `pre-review-checks.py`, which runs automated structural checks before the LLM evaluation. No controller is needed — this is a single-phase workflow.
 
 ## Workflow Phase
 
@@ -35,7 +39,8 @@ The **command** (`commands/review.md`) is a thin wrapper that routes directly to
 **Purpose**: Perform a deep, skeptical review of an AI skill directory.
 
 1. Read all files in the target skill directory (`SKILL.md`, `skills/*.md`, `commands/*.md`, `guidelines.md`, `README.md`)
-2. Evaluate against 8 review dimensions:
+2. Run automated pre-review checks (`scripts/pre-review-checks.py`) — structural validation, frontmatter, orphaned/dangling references, step sequencing
+3. Evaluate against 8 review dimensions (using automated check results as pre-validated evidence):
    - **Orchestration & Routing** — correct routing, no orphaned or dangling references
    - **Step Sequencing & Numbering** — sequential numbering, correct cross-references
    - **Schema Consistency** — matching field names/types across files
@@ -44,7 +49,7 @@ The **command** (`commands/review.md`) is a thin wrapper that routes directly to
    - **Documentation & Project Alignment** — README matches implementation, consistent with sibling skills and project conventions
    - **Command Naming** — consistent, self-explanatory names
    - **Error Handling & Edge Cases** — failure modes documented, escalation clear
-3. Classify findings by severity and produce a structured report
+4. Classify findings by severity and produce a structured report
 
 **Output**: `.artifacts/skill-reviewer/{skill-name}/review.md` + findings presented inline.
 
@@ -95,6 +100,8 @@ Agent works through findings from highest severity to lowest.
 
 ```text
 .artifacts/skill-reviewer/{skill-name}/
+├── file-hashes.json    # SHA-256 hashes for change detection between reviews
+├── skill-map.md        # Structured skill map (comprehension artifact before evaluation)
 └── review.md           # Full review report with findings table
 ```
 

skill-reviewer/SKILL.md

@@ -13,7 +13,8 @@ description: >-
 Run `/review` to execute the full workflow. The user must specify which skill directory to review (e.g. `bugfix/`, `docs-writer/`). Executable without opening other files:
 
 1. Read every file in the target skill directory: `SKILL.md`, `skills/*.md`, `commands/*.md`, `guidelines.md`, `README.md`. If the directory doesn't exist or has no skill files, report the error and stop. Note any missing files — gaps are themselves a finding.
-2. Evaluate against 8 dimensions:
+2. Run automated pre-review checks: `python3 {skill-reviewer-dir}/scripts/pre-review-checks.py {target-dir}` — captures structural, frontmatter, reference, and sequencing issues deterministically. Treat `FAIL` results as pre-validated findings; apply judgment to `WARN` results. If the script is not present, skip and check manually.
+3. Evaluate against 8 dimensions (use automated check results as pre-validated evidence where available):
    - **Orchestration & Routing** — correct routing, no orphaned/dangling references, executable Quick Start
    - **Step Sequencing** — sequential numbering, correct cross-references, logical order
    - **Schema Consistency** — matching field names/types across files, schema visible before first use
@@ -22,9 +23,9 @@ Run `/review` to execute the full workflow. The user must specify which skill di
    - **Documentation & Project Alignment** — README matches implementation, consistent with sibling skills and project conventions
    - **Command Naming** — consistent pattern (verbs vs nouns), self-explanatory
    - **Error Handling** — failure modes documented, escalation paths clear
-3. Classify each finding by severity — **CRITICAL** / **HIGH** (blockers) or **MEDIUM** / **LOW** (suggestions).
-4. Validate findings: verify each finding cites a specific file, includes a concrete suggestion, and that blocker/suggestion counts are accurate. Drop any finding you cannot substantiate from the files you read.
-5. Produce a structured report and write it to `.artifacts/skill-reviewer/{skill-name}/review.md`:
+4. Classify each finding by severity — **CRITICAL** / **HIGH** (blockers) or **MEDIUM** / **LOW** (suggestions).
+5. Validate findings: verify each finding cites a specific file, includes a concrete suggestion, and that blocker/suggestion counts are accurate. Drop any finding you cannot substantiate from the files you read.
+6. Produce a structured report and write it to `.artifacts/skill-reviewer/{skill-name}/review.md`:
 
 ```
 ## Skill Review: {skill-name}
@@ -56,6 +57,10 @@ skill-reviewer/
   README.md             # User-facing documentation
   commands/
     review.md           # /review command — loads guidelines + skill
+  prompts/
+    analyze-skill.md    # Prompt template for Explore sub-agent (large skill reading)
   skills/
     review.md           # The review skill (detailed steps and output format)
+  scripts/
+    pre-review-checks.py  # Automated structural/reference/sequencing checks
 ```

skill-reviewer/guidelines.md

@@ -14,6 +14,7 @@ Artifacts go in `.artifacts/skill-reviewer/{skill-name}/`.
 - Be constructive — every finding should include a concrete suggestion.
 - If something is broken, say so — don't minimize or hedge.
 - Distinguish between blockers (must fix) and suggestions (nice to have).
+- Offload mechanical checks to `scripts/pre-review-checks.py` when available — focus reviewer attention on judgment calls that require reading comprehension and context.
 
 ## Hard Limits
 
@@ -34,6 +35,8 @@ Artifacts go in `.artifacts/skill-reviewer/{skill-name}/`.
 - Findings must be classified by severity (CRITICAL / HIGH / MEDIUM / LOW)
 - The report must follow the structured output format defined in the review skill
 - Blocker and suggestion counts must be accurate
+- Script `FAIL` results are pre-validated (verified against the filesystem) and can be cited directly as findings without re-verification
+- Script `WARN` results require reviewer judgment — not all warnings are findings
 
 ## Escalation
 

skill-reviewer/prompts/analyze-skill.md

@@ -0,0 +1,137 @@
+# Skill Analysis Prompt
+
+You are an Explore agent. Your job is to read every file in a skill directory
+and produce a structured **skill map** that faithfully summarizes what you read.
+You do **not** evaluate, judge, or recommend. You comprehend and report.
+
+## Target
+
+Skill directory: `{target-skill-directory}`
+Skill name: `{skill-name}`
+
+## Reading Order
+
+Read each file **in full**. Do not skip any file. Read in this order:
+
+1. `SKILL.md` (orchestrator — overall structure and routing)
+2. `guidelines.md` (principles and constraints)
+3. `commands/*.md` (command routers — how users enter the workflow)
+4. `skills/*.md` (phase/step skills, including `controller.md` — the detailed logic)
+5. `README.md` (user-facing documentation)
+6. Any other directories and files (`templates/`, `scripts/`, etc.)
+
+If a file is missing, note its absence in the File Inventory.
+
+## Output
+
+Write the skill map to `.artifacts/skill-reviewer/{skill-name}/skill-map.md`
+using the structure below. After writing, return to the caller — do not take
+any further action.
+
+---
+
+## Skill Map Structure
+
+Use these exact section headings. If a section has no content (e.g., no schemas
+found), write "None found." under the heading — do not omit the section.
+
+### File Inventory
+
+| Path | Type | Lines | Purpose |
+|------|------|-------|---------|
+| SKILL.md | orchestrator | 62 | Entry point with phase overview and routing |
+| guidelines.md | guideline | 53 | Principles, hard limits, safety rules |
+| commands/fix.md | command | 12 | Thin wrapper routing to controller for /fix |
+| skills/controller.md | skill | 145 | Phase dispatcher and transition logic |
+| ... | ... | ... | ... |
+
+**Type** values: `orchestrator`, `guideline`, `command`, `skill`, `template`,
+`script`, `doc`, `other`.
+
+Mark missing expected files with type `missing`:
+
+| Path | Type | Lines | Purpose |
+|------|------|-------|---------|
+| guidelines.md | missing | — | Not found in directory |
+
+### Routing Graph
+
+List every file-to-file reference as an edge. Include the direction of reference
+(which file mentions which). Use relative paths from the skill root.
+
+```
+SKILL.md → guidelines.md
+SKILL.md → skills/controller.md
+commands/fix.md → skills/controller.md
+skills/controller.md → skills/fix.md
+skills/controller.md → skills/test.md
+skills/fix.md → (none — no outgoing references)
+```
+
+### Phase Pipeline
+
+Ordered list of phases as they appear in the workflow. For each phase:
+
+- **Phase name** and command (e.g., `/fix`)
+- **Purpose**: one sentence
+- **Skill file**: which file implements it
+- **Key inputs**: what the phase reads or requires
+- **Key outputs**: what the phase produces (files, artifacts, state changes)
+
+If the workflow has no explicit phases (single-phase workflow), describe the
+single phase.
+
+### Schema Fields
+
+For each data schema, structured data format, or artifact template found:
+
+- **Where introduced**: file and step where the schema is first defined
+- **Where consumed**: file(s) and step(s) where the schema fields are read
+- **Fields**: field names and types/descriptions
+
+If no explicit schemas are found, write "None found."
+
+### Step Sequences
+
+For each file in `skills/` that uses step headings:
+
+- **File**: relative path
+- **Steps**: numbered list of step headings as they appear (e.g., "Step 1: Identify the Target")
+- **Cross-references**: any "see Step N" or "from Step N" references, noting which step/file they point to
+- **Total step count**: number of steps in the file
+
+### Command Names
+
+| Command | Frontmatter name | Routes to |
+|---------|-----------------|-----------|
+| /fix | bugfix:fix | skills/controller.md |
+| /test | bugfix:test | skills/controller.md |
+| ... | ... | ... |
+
+### Key Constraints
+
+From `guidelines.md` (and any constraints stated in `SKILL.md`), list:
+
+- **Principles** (bulleted)
+- **Hard limits** (bulleted)
+- **Safety rules** (bulleted)
+- **Quality standards** (bulleted)
+- **Escalation criteria** (bulleted)
+
+If `guidelines.md` is missing, note this and extract any constraints visible
+in `SKILL.md` or `README.md`.
+
+---
+
+## Constraints for You
+
+- Do **not** evaluate the quality of the skill. Do not say "this is good" or
+  "this could be improved."
+- Do **not** form opinions. Report what each file says, not what you think
+  about it.
+- Do **not** omit files. If a file exists in the directory, it must appear in
+  the File Inventory.
+- Do **not** invent information. If something is unclear or ambiguous, report
+  it as-is and add "(ambiguous)" or "(unclear)".
+- Do **not** summarize file contents beyond what each section asks for. The
+  skill map is a structured index, not a paraphrase.