levnikolaevich/ln-162-skill-reviewer

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

ln-162-skill-reviewer

Type: L3 Worker (standalone-capable) Category: 1XX Documentation Pipeline

Universal reviewer with two modes:

• SKILL for ln-*/SKILL.md
• COMMAND for .claude/commands/*.md
• repo suite for this skills repository when repo / repo-checks is requested or the current repo is claude-code-skills

Plan Mode behavior: Phases 1-4 and 6-7 are research. Run them fully in Plan Mode, write the report plus fix list into the plan, and apply edits only after approval.

---

Mode Detection

| Condition | Mode | Review Profile | |-----------|------|----------------| | ln-*/SKILL.md files exist in CWD | SKILL | Full D1-D11 + M1-M6 | | .claude/commands/*.md files exist | COMMAND | Structural + actionability | | Both exist | SKILL | Override with $ARGUMENTS=commands |

Input

$ARGUMENTS options:

• empty -> auto-detect mode and scope
• ln-400 ln-500 -> SKILL mode, specific skills
• repo or repo-checks -> run canonical repo-specific checks after universal review
• commands -> COMMAND mode, all .claude/commands/*.md
• deploy.md run-tests.md -> COMMAND mode, specific files

When invoked by another skill, file paths may be passed directly.

---

SKILL Mode

Phase 1: Scope Detection

If $ARGUMENTS is provided:

• treat each token as a skill directory prefix
• glob {prefix}*/SKILL.md

If $ARGUMENTS is empty:

• inspect git diff, staged files, and untracked files
• collect primary skill dirs
• collect affected skills referencing changed shared files
• collect dependency skills from worker tables and Skill() invocations

Report: Scope: {N} primary, {M} affected, {K} dependency skills.

Phase 2: Automated Verification

Run:

# Never pass a giant mixed scope in one invocation.
# Split by `ln-NXX` family or by coordinator/worker group.
bash references/run_checks.sh {batch_1 SKILL.md files}
bash references/run_checks.sh {batch_2 SKILL.md files}

Batching rules:

• keep each invocation within one ln-NXX family when possible
• if scope mixes coordinators and workers, split them into separate invocations
• if one family is still large, chunk it into 5-10 files per invocation

Automated failures are pre-verified. Record every one.

Phase 3: Structural Review

MANDATORY READ: Load references/structural_review.md, shared/references/skill_contract.md, shared/references/procedural_skill_sop_guide.md, shared/references/mcp_applicability_matrix.md, and shared/references/mcp_tool_preferences.md

Review every skill in scope across D1-D11.

Treat these as structural issues, not style nits:

• missing **Type:** when role-sensitive checks depend on it
• worker independence violations in L3 workers
• broken shared paths
• stale root-doc assumptions — CLAUDE.md duplicating AGENTS.md content instead of using the @AGENTS.md import stub with a bounded harness delta
• markdown-analysis skills missing markdown_read_protocol.md
• extraction or audit skills contradicting the shared docs-quality contract
• skills contradicting the shared skill contract
• skills that should make hex-line primary but only describe built-in file tools
• skills that should make hex-graph primary but still describe grep/manual analysis as the default path
• skills that add hex-graph or hex-line with no real applicability per the shared matrix
• wrong MCP namespaces such as mcp__hex_graph__...
• procedural skills with vague modal words, compound high-risk steps, missing point-of-use checklists, missing why for risky steps, missing executable preflight, or missing evidence

Phase 4: Intent Review

MANDATORY READ: Load references/intent_review.md

Apply M1-M6 to primary skills only. Read the git diff for each primary skill.

Phase 5: Fix

Auto-fix deterministic issues:

• wrong paths
• stale references
• duplicated wording
• worker-independence violations with exact removals
• copied docs shell sections in command files

Do not guess on ambiguous behavior.

After fixes, re-read each primary skill end-to-end and compress redundant wording without changing behavior.

Phase 6: Report

Verdict rules:

• any structural violation not auto-fixed -> FAIL
• only advisory intent concerns remain -> PASS with CONCERNS
• zero findings -> PASS

Report format:

## Skill Coherence Review -- {PASS|PASS with CONCERNS|FAIL}

**Scope:** {reviewed skills}
**Verdict:** {verdict}

Phase 7: Volatile Numbers Cleanup

Remove stale aggregate counts from SKILL.md files. Keep only local counts intrinsic to the reviewed file.

---

Repo Suite Mode

Use when running inside this repository or when $ARGUMENTS includes repo / repo-checks.

Phase 1: Universal Review

Run the applicable SKILL or COMMAND mode first. Do not skip the universal review.

Phase 2: Repo-Specific Checks

Run the canonical repo suite:

node skills-catalog/ln-162-skill-reviewer/references/repo_review_suite.mjs

The suite owns R1-R27. Do not copy those checks into host-specific command files.

Phase 3: Combined Report

Merge the universal review verdict and repo suite verdict:

| Source | Verdict | Details |
|--------|---------|---------|
| Universal review | {PASS|PASS with CONCERNS|FAIL} | {summary} |
| Repo suite | {PASS|PASS with WARNINGS|FAIL} | {R1-R27 summary} |
| Combined | {worst verdict} | |

List all FAIL and WARN items with file paths and fix descriptions.

---

COMMAND Mode

MANDATORY READ: Load references/command_review_criteria.md

Phase 1: Scope Detection

• explicit file paths -> review those files
• commands -> glob .claude/commands/*.md
• coordinator-supplied file list -> review those files

Phase 2: Review

For each command file:

• apply all command review criteria
• verify source provenance
• verify no copied docs shell sections remain

Phase 3: Fix

Auto-fix where safe:

• missing frontmatter
• missing allowed-tools
• description too long
• missing Last Updated
• exact copied docs shell sections

Phase 4: Report

## Command Review -- {N} files

| File | Verdict | Issues |
|------|---------|--------|

Verdicts: PASS / FIXED / WARN / FAIL
Pass rate: {X}%

---

Rules

• Automated checks are non-negotiable.
• Read all scoped files before reporting.
• Fix deterministic issues immediately.
• Do not update versions or dates unless the user explicitly requests it.
• shared/ changes affect all referencing skills.
• Worker independence is mandatory for L3 workers:
  • no **Coordinator:**
  • no **Parent:**
  • no required caller declaration
• Docs-model drift is a structural defect, not a preference.
• Unsupported platform APIs are prohibited outside clearly marked historical references.

Reference Files

• references/structural_review.md
• references/intent_review.md
• references/automated_checks.md
• references/run_checks.sh
• references/run_runtime_suite.mjs
• references/repo_review_suite.mjs
• references/command_review_criteria.md
• references/check_marketplace.mjs

Definition of Done

• [ ] Scope detected
• [ ] Automated checks executed
• [ ] D1-D11 reviewed across all scoped skills
• [ ] M1-M6 evaluated for primary skills
• [ ] Fixable findings auto-fixed
• [ ] Post-fix holistic compaction completed
• [ ] Final verdict report generated

---

Version: 1.0.0 Last Updated: 2026-03-26