Review Skill Workflow

You are helping an SME review an Agent Skill before publishing. This is a multi-step process: determine environment, verify prerequisites, run structural validation, review content, optionally run LLM scoring, and interpret results. Follow every step in order.

Step 0: Determine Environment

Check for saved configuration:

cat ~/.config/skill-validator-ent/review-state.yaml 2>/dev/null

If the state file exists with prereqs_passed: true, offer:

Found saved settings — configured for [bedrock/structural-only] reviews.

Continue with saved settings — skip to Step 2

Re-run prerequisite checks

Change environment — switch between Bedrock and structural-only

Option 1: read llm_scoring from the file and skip to Step 2. Options 2-3: continue below.

If no state file exists, or the user chose to re-check/change, ask:

LLM scoring uses Claude via AWS Bedrock. Without Bedrock, we run structural validation only.

Yes, I have AWS Bedrock access — full review with LLM scoring

No, skip LLM scoring — structural validation only

Option 1: set LLM_SCORING=true. After Step 1a, follow references/bedrock-llm-scoring.md for Bedrock checks before Step 2. Option 2: set LLM_SCORING=false. Run Step 1a only, then jump to Step 2.

Step 1: Verify Prerequisites

1a. Check for `skill-validator-ent` binary

skill-validator-ent --version

If not found, search common locations (/usr/local/bin, /opt/homebrew/bin, ~/go/bin). If found but not on PATH, tell the user. If not found anywhere, follow references/install-skill-validator-ent.md.

Do NOT proceed until this succeeds.

If LLM_SCORING=true, complete the Bedrock prerequisite checks in references/bedrock-llm-scoring.md before continuing.

Save state after prerequisites pass

Persist state so future runs skip this step. Replace <true or false> with the actual LLM_SCORING value:

mkdir -p ~/.config/skill-validator-ent
cat > ~/.config/skill-validator-ent/review-state.yaml << 'EOF'
prereqs_passed: true
llm_scoring: <true or false>
EOF

Step 2: Locate the Skill

Ask the user for the path to the skill they want to review, unless they have already provided it. Verify the path contains a SKILL.md file:

ls <path>/SKILL.md

If SKILL.md does not exist at the given path, tell the user this is not a valid skill directory and ask them to provide the correct path.

Step 3: Run Structural Validation

Run the full check suite:

skill-validator-ent check <path>

Capture the exit code:

Exit code	Meaning
0	Clean — no errors or warnings
1	Errors found — must fix before publishing
2	Warnings only — review but not blocking
3	CLI/usage error — check the command

Exit 0: proceed. Exit 2: note warnings, proceed. Exit 1: list errors — these are blocking. The user must fix them before the skill can be published. Do NOT proceed to LLM scoring if exit code is 1.

Step 4: Content Review

Read the SKILL.md and any reference files, then evaluate each check below. Report which checks pass and which do not, with specific details on what is missing.

Check	Criteria
Examples	Does the skill provide examples of expected inputs and outputs?
Edge cases	Does the skill document common edge cases or failure modes?
Scope-gating	Does the skill define when to stop/continue, prerequisites, and conditions for branching paths?
MongoDB data access	If the skill needs MongoDB contextual data, does it instruct agents to use the MCP server for auth and tool calls? Skip if not applicable.

Flag any failing checks as areas the SME should address. These are not blocking but should be resolved before publishing for best results.

Step 5: LLM Scoring and Interpretation (Bedrock users only)

If LLM_SCORING=false, skip to Step 6.

If LLM_SCORING=true, follow the "Run LLM Scoring" and "Interpret LLM Scores" sections of references/bedrock-llm-scoring.md.

Step 6: Present the Review Summary

If LLM_SCORING=true, follow the "Full Review Summary" section of references/bedrock-llm-scoring.md. Include any failing content review checks from Step 4 in the action items.

If LLM_SCORING=false, present structural result, content review result, areas to address, and a self-assessment checklist using the scoring dimensions from assets/report.md. Note that LLM scoring was skipped; advise re-running with Bedrock access or self-assessing against the report dimensions.

Example Review Summary Structure

Structure the final summary with these sections in order:

Structural validation — pass/fail with errors or warnings
SKILL.md scores — overall and per-dimension table
Reference scores — per-file table with overall and lowest dimension
Novelty assessment — mean novelty vs threshold of 3; list novel_info per file for SME verification
Action items — prioritized list of what to fix
Recommendation — ready to publish / minor revisions / significant rework

review-skill