skill-reviewing

name	skill-reviewing
description	Comprehensive review of Claude Code skills and agents against v0.5 guidelines. Validates metadata, implementation, and architecture. Use when reviewing existing packages or during skill development.

Skill Reviewing

Provides comprehensive validation of Claude Code skills and agents against:

• Plugin Storage Conventions (NORMATIVE)
• Agent Tool Use Best Practices
• Architecture Guidelines v0.5

Capabilities

This skill orchestrates three specialized review agents, each focusing on a distinct concern:

Agent	Focus	Source Document
skill-metadata-storage-review	Frontmatter & persistence	PLUGIN-STORAGE-CONVENTIONS.md
skill-implementation-review	Code mechanics & security	agent-tool-use-best-practices.md
skill-architecture-review	Design patterns & structure	claude-code-skills-agents-guidelines-0.4.md

Agent Delegation

All three agents are invoked via Agent Runner for parallel execution:

Metadata & Storage Reviewer

Validates:

• YAML frontmatter (name, version, description)
• Version consistency with registry.yaml
• Storage paths (logs, settings, outputs)
• Secret handling
• Documentation completeness

Returns: {success, data: {checks_performed, checks_passed, warnings, errors}, error}

Implementation Reviewer

Validates:

• JSON fencing
• Hook implementation (Python preferred)
• Dependency declarations
• Security patterns
• Cross-platform compatibility

Returns: {success, data: {checks_performed, checks_passed, warnings, errors}, error}

Architecture Reviewer

Validates:

• Two-tier skill/agent separation
• Response contract compliance
• Single responsibility principle
• Agent size and complexity
• File organization

Returns: {success, data: {checks_performed, checks_passed, warnings, errors}, error}

Orchestration Pattern

When user requests a review:

1. Determine target

   • Parse user input to identify what to review
   • Resolve to absolute path if needed
   • Determine target_type: "agent", "skill", or "package"

2. Invoke agents in parallel Use Agent Runner to invoke all three reviewers concurrently with parameters:

   For skill-metadata-storage-review:

   {
     "target_type": "<agent|skill|package>",
     "target_path": "/absolute/path/to/target",
     "package_name": "<package-name-if-applicable>",
     "check_registry": true,
     "registry_path": ".claude/agents/registry.yaml"
   }
   

   For skill-implementation-review:

   {
     "target_path": "/absolute/path/to/target",
     "check_hooks": true,
     "check_dependencies": true,
     "check_security": true,
     "manifest_path": "manifest.yaml"
   }
   

   For skill-architecture-review:

   {
     "target_type": "<agent|skill|package>",
     "target_path": "/absolute/path/to/target",
     "check_two_tier": true,
     "check_contracts": true,
     "check_naming": true,
     "registry_path": ".claude/agents/registry.yaml"
   }
   

3. Aggregate results

   • Collect fenced JSON from all three agents
   • Parse and merge findings
   • Group by severity: errors, warnings, info
   • Organize by concern area (metadata, implementation, architecture)

4. Format report Present findings to user in this structure:

   ## Review Summary: [package-name]
   
   ✅ Metadata & Storage: X checks passed, Y warnings, Z errors
   ⚠️  Implementation: X checks passed, Y warnings, Z errors
   ✅ Architecture: X checks passed, Y warnings, Z errors
   
   ### Critical Issues (must fix)
   [List all errors with file:line and suggested actions]
   
   ### Warnings (should fix)
   [List all warnings with suggestions]
   
   ### Info (optional improvements)
   [List all info-level findings]
   

Usage Examples

Review entire package:

/skill-reviewing sc-managing-worktrees

Review specific agent:

/skill-reviewing .claude/agents/sc-worktree-create.md

Review skill:

/skill-reviewing .claude/skills/managing-worktrees/

Review during development:

Review the skill I just created in .claude/skills/my-new-skill/

Error Handling

If Any Reviewer Fails

• Report which reviewer failed and why
• Include partial results from successful reviewers
• Suggest corrective action (e.g., "Registry file not found at .claude/agents/registry.yaml")
• Do not fail entire review if one agent has issues

If All Reviewers Return No Issues

• Congratulate user on clean implementation
• Show summary: "All X checks passed across metadata, implementation, and architecture"
• Optionally suggest next steps (testing, documentation improvements)

If Target Not Found

• Return clear error message
• Suggest correct paths for common targets
• Examples:
  • Agents: .claude/agents/<name>.md
  • Skills: .claude/skills/<name>/SKILL.md
  • Packages: packages/<name>/

Notes

• Parallel Execution: All three agents run independently in isolated contexts
• Structured Output: Each agent returns fenced JSON for reliable parsing
• Read-Only: No agent modifies files; this is analysis only
• Comprehensive: Covers three orthogonal concerns for complete validation
• Actionable: Every finding includes suggested_action for quick fixes

Related Documentation

• Design Document — Complete specification
• Architecture Guidelines v0.5 — Source guidelines
• Plugin Storage Conventions — NORMATIVE storage rules
• Tool Use Best Practices — Implementation patterns