
Review Skill
- 25 installs
- 74 repo stars
- Updated July 21, 2026
- existential-birds/beagle
Helps with ai & agent building tasks.
About
review-skill is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.
- review-skill
- AI & Agent Building
- AI-coding skill
Review Skill by the numbers
- 25 all-time installs (skills.sh)
- Ranked #9,800 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Jul 28, 2026 (Skillselion catalog sync)
npx skills add https://github.com/existential-birds/beagle --skill review-skillAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 25 |
|---|---|
| repo stars | ★ 74 |
| Last updated | July 21, 2026 |
| Repository | existential-birds/beagle ↗ |
What it does
Helps with ai & agent building tasks.
Files
Skill Review
Review Agent Skill PRs for structural validity, design quality, and marketplace consistency.
Arguments
$ARGUMENTS: Output file path for review results (required, passed by the calling harness or the user)--base <branch>: Base branch for diff comparison (default:main)
Workflow
Step 1: Parse Arguments
Extract the output path from $ARGUMENTS. If no path is provided, default to .review-output.md. Extract --base if provided, otherwise default to main.
Step 2: Identify Changed Skills
git diff --name-only $(git merge-base HEAD <base>)..<HEAD> | grep -E '(SKILL\.md|skills/[^/]+/)'Group changed files by skill directory. Each unique skill directory is a review target. If no skill files changed, write "No skill files changed" to the output path and stop.
Step 3: Read Each Changed Skill End-to-End
For each changed skill: 1. Read the full SKILL.md (not just diff lines) 2. Read all files in the skill directory (references, scripts) 3. Note the parent plugin directory and locate its plugin.json
Step 4: Run Structural Checks (HIGH Confidence)
Apply every check in references/structural-checks.md. These are binary pass/fail — violations are clear-cut.
Structural violations are HIGH confidence because they can be verified mechanically.
Step 5: Run Design Checks (MEDIUM Confidence)
Apply every check in references/design-checks.md. These require judgment — flag only when the issue is clear, not when the approach is merely different from what you'd choose.
Design issues are MEDIUM confidence because they involve subjective assessment.
Step 6: Run Marketplace Checks (HIGH Confidence)
Apply every check in references/marketplace-checks.md. These verify the skill integrates correctly with the marketplace it belongs to.
Marketplace violations are HIGH confidence because they can be verified by reading manifest files.
Step 7: Load and Apply Verification Protocol
Load the review-verification-protocol skill. Before reporting any finding, verify:
1. You read the actual skill content, not just the diff context 2. The issue is real, not a style preference 3. The issue applies to skill files specifically (not general code review concerns) 4. You can point to the specific line that proves the issue
Remove any finding you cannot verify.
Step 8: Write Output
Write all findings to the output path specified in Step 1, using the exact format below.
Output Format
## Review Summary
[1-2 sentence overview of findings across all reviewed skills]
## Issues
### Critical (Blocking)
1. [FILE:LINE] ISSUE_TITLE
- Issue: Description of what's wrong
- Why: Why this matters for skill quality or marketplace health
- Fix: Specific recommended fix
- Confidence: HIGH
### Major (Should Fix)
N. [FILE:LINE] ISSUE_TITLE
- Issue: ...
- Why: ...
- Fix: ...
- Confidence: HIGH|MEDIUM
### Minor (Nice to Have)
N. [FILE:LINE] ISSUE_TITLE
- Issue: ...
- Why: ...
- Fix: ...
- Confidence: HIGH|MEDIUM
### Informational (For Awareness)
N. [FILE:LINE] SUGGESTION_TITLE
- Suggestion: ...
- Rationale: ...
- Confidence: MEDIUM
## Verdict
Ready: Yes | No | With fixes 1-N
Rationale: [1-2 sentences — only Critical and Major items block approval]Every issue gets a sequential number. Every issue includes Confidence: HIGH|MEDIUM. The Verdict ignores Minor and Informational items.
Severity Calibration
Critical (Block Merge)
- Invalid or missing YAML frontmatter (skill won't load)
- Missing required
nameordescriptionfield - SKILL.md exceeds 500 lines (performance degradation)
- Name collision with existing skill in the marketplace
Major (Should Fix)
nameviolates format rules (not kebab-case, too long, reserved word)descriptionmissing "what" or "when" component, wrong person, or exceeds 1024 chars- Nested reference chains (references that reference other references)
- Description too vague to trigger accurately
- Structured output with no format template or example
- Windows-style paths in file references
Minor (Nice to Have)
- Time-sensitive content (hardcoded dates, "recently", "new")
- Inconsistent terminology across skill files
- Progressive disclosure not used when SKILL.md is dense
- Workflows missing validation steps
- Missing cross-reference (SKILL.md links to file that doesn't exist)
Informational (For Awareness)
- Trigger keyword overlap with existing marketplace skills
- Suggestions for additional reference files
- Opportunities to improve description specificity
- Script lacks
--helpor uses interactive prompts
Re-Review Rules
On subsequent review passes after fixes are applied: 1. ONLY verify that previously flagged issues were addressed correctly 2. Do NOT introduce new findings unrelated to previous issues 3. Accept Minor items that weren't fixed — do not re-flag 4. The goal of re-review is verification, not discovery
References
- Structural checks: references/structural-checks.md — frontmatter, naming, line limits, path format
- Design checks: references/design-checks.md — description quality, progressive disclosure, degrees of freedom
- Marketplace checks: references/marketplace-checks.md — name collision, plugin.json consistency, trigger overlap
Design Checks
All design checks emit MEDIUM confidence issues. These involve judgment — flag only when the problem is clear, not when the approach is merely different from what you'd choose.
Description Trigger Quality
Specific Enough to Trigger Accurately
What to check: The description provides enough specificity that an agent can distinguish this skill from others in a marketplace with 100+ skills. Generic descriptions cause over-triggering (selected for unrelated tasks) or under-triggering (missed for relevant tasks).
How to verify: Ask: "If I had 100 skills loaded, would this description uniquely identify when to use this one?" Check for:
- Specific domain terms (not just "code", "files", "data")
- Concrete trigger conditions (not just "Use when needed")
- Technology or format names when applicable
Good examples:
# Specific domain + concrete triggers
description: Reviews Go code for idiomatic patterns, error handling, concurrency safety, and common mistakes. Use when reviewing .go files, checking error handling, goroutine usage, or interface design.
# Clear capability boundary + activation context
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.Bad examples:
# Too vague — matches almost anything
description: Helps with code quality
# No trigger context — when should this activate?
description: Processes documents and generates output
# Overly broad — would trigger on any development task
description: Assists with software development tasks and best practicesWhen NOT to flag: A description that covers a genuinely broad domain (e.g., a general Python review skill) is fine as long as the trigger conditions are specific. Breadth of capability is different from vagueness of description.
Not Overlapping Excessively with Other Skills
What to check: The description's trigger surface doesn't substantially duplicate another skill in the same marketplace. Some overlap is expected (a Python review skill and a FastAPI review skill both mention Python), but the descriptions should have distinct primary trigger conditions.
How to verify: Compare the new/changed skill's description against other skills in the same plugin and marketplace. Flag if the primary trigger keywords are nearly identical and the capability statements don't differentiate.
When NOT to flag: Complementary skills that cover different aspects of the same domain (e.g., review-python for general Python and review-fastapi for FastAPI-specific patterns) are expected to share some keywords.
Progressive Disclosure
Main Concepts in SKILL.md, Details in References
What to check: SKILL.md provides the core workflow and navigation. Detailed reference material, extensive examples, API specifications, and long checklists live in separate reference files.
How to verify: Check if SKILL.md contains:
- Long code examples (>20 lines) that could be in a reference file
- Detailed API specifications or schema definitions
- Exhaustive checklists (>15 items) without summarization
- Content that only applies to specific sub-tasks (should load on demand)
Good pattern:
# SKILL.md
## Quick Start
[3-5 lines]
## Workflow
[Core steps with brief descriptions]
## References
- Detailed API reference: [reference.md](reference.md)
- Extended examples: [examples.md](examples.md)Bad pattern:
# SKILL.md (400+ lines)
## API Reference
[200 lines of API details]
## Examples
[150 lines of examples]
## Edge Cases
[50 lines of edge cases]When NOT to flag:
- Simple skills under 200 lines that don't need splitting
- Skills where all content is essential for every invocation (no conditional loading benefit)
- Skills that are already well under the 500-line limit
Reference Files Organized by Domain
What to check: When a skill has multiple reference files, they're organized so the agent can load only what's relevant to the current task.
How to verify: Each reference file should serve a distinct purpose or domain. Files named reference1.md, reference2.md are a smell — prefer descriptive names like api-errors.md, migration-patterns.md.
When NOT to flag: Skills with a single reference file don't need domain organization.
Degrees of Freedom
Calibrated to Task Fragility
What to check: Instructions match their specificity to the task's fragility:
- High freedom (text-based guidance) for judgment calls where multiple approaches are valid
- Medium freedom (templates/pseudocode with parameters) for tasks with a preferred pattern but acceptable variation
- Low freedom (exact commands, no modification) for fragile operations where consistency is critical
How to verify: Look for mismatches:
- Overly prescriptive instructions for flexible tasks (e.g., exact code for a code review process)
- Overly vague instructions for fragile tasks (e.g., "run the migration script" without specifying the exact command and flags)
Good examples:
# High freedom — code review (judgment-based)
1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability
# Low freedom — database migration (fragile)
Run exactly: `python scripts/migrate.py --verify --backup`
Do not modify the command or add additional flags.Bad examples:
# Over-prescriptive for a flexible task
When reviewing code, always check line 1 first, then line 2...
# Under-specified for a fragile task
Run the migration script with appropriate flags.When NOT to flag: When the skill consistently uses one freedom level and the domain justifies it (e.g., a deployment skill that is entirely low-freedom because every step is fragile).
Implementation Leakage
No Unjustified Library/Tool Prescription
What to check: The skill doesn't prescribe specific libraries, tools, or implementations when the domain doesn't require them. A skill providing guidance should describe what to do and why, leaving how to the agent's judgment unless a specific tool is genuinely the only or clearly best option.
How to verify: For each library/tool mentioned, ask: "Is this the only reasonable choice, or is the skill leaking implementation preference?" Signals of leakage:
- Mandating a specific HTTP client when any would work
- Requiring a particular testing framework when the project may use a different one
- Prescribing a specific editor command or IDE feature
When NOT to flag:
- Skills that are explicitly about a specific tool (e.g., "pdfplumber patterns")
- Cases where a specific tool is genuinely necessary (e.g., a migration script that must use the project's own migrator)
- Utility scripts bundled with the skill (these are part of the skill, not leaked preferences)
Workflow Quality
Validation Steps Present
What to check: Multi-step workflows include validation or verification steps — they don't fire-and-forget. After a significant action, the workflow should verify the result before proceeding.
How to verify: For each workflow with 3+ steps, check that at least one step involves validation, verification, or a check-before-proceeding gate. Look for patterns like:
- "Run validation"
- "Verify output"
- "Check that X before proceeding"
- "If validation fails, return to step N"
When NOT to flag:
- Simple workflows (1-2 steps) where the action is self-contained
- Workflows where the final step is inherently a verification (e.g., "run tests")
- Read-only workflows that don't produce artifacts
No Fire-and-Forget Destructive Operations
What to check: If the workflow involves writing files, modifying state, or executing commands with side effects, there's a verification step after the operation.
When NOT to flag: Operations that are inherently safe or reversible (e.g., writing to a temp file, creating a git branch).
Output Format Specification
Structured Output Has Template or Example
What to check: When a skill produces structured output (reports, reviews, formatted documents, data files), the expected format is specified via a template or a concrete example. Prose descriptions of format are insufficient for consistent output.
How to verify: If the skill's workflow produces a file or structured response, check that SKILL.md or a reference file contains either:
- A template with placeholders showing the exact structure
- A concrete example of the expected output
- Both (template for structure, example for style)
Good pattern: ````markdown
Output Format
## Summary
[1-2 sentences]
## Findings
1. [FILE:LINE] TITLE
- Issue: ...
- Fix: ...````
Bad pattern:
## Output Format
Write a summary followed by a list of findings with file locations.When NOT to flag:
- Skills that produce free-form text (creative writing, explanations)
- Skills where the output format is inherently determined by the task (e.g., "generate a commit message")
Marketplace Checks
All marketplace checks emit HIGH confidence issues. These are verifiable by reading manifest files and enumerating directories.
This document is marketplace-agnostic — it works against any Agent Skills marketplace that uses plugin.json manifests. It does not hardcode marketplace names, directory conventions, or organization-specific rules.
Discovering the Marketplace Structure
Before running marketplace checks, build a map of the marketplace:
1. Find the marketplace manifest — look for a top-level manifest file (e.g., marketplace.json, .claude-plugin/marketplace.json, or similar) that lists plugins. If no manifest exists, fall back to scanning for plugin.json files.
2. Enumerate plugins — for each plugin entry in the manifest, read its source path to find the plugin directory. Read the plugin's plugin.json for metadata.
3. Enumerate skills per plugin — within each plugin directory, look for a skills/ directory. Each subdirectory of skills/ that contains a SKILL.md is a skill.
4. Build the skill index — collect all (plugin_name, skill_name, description) tuples. This index is used for collision detection and overlap analysis.
Marketplace
├── Plugin A (plugin.json)
│ └── skills/
│ ├── skill-one/SKILL.md
│ └── skill-two/SKILL.md
├── Plugin B (plugin.json)
│ └── skills/
│ ├── skill-three/SKILL.md
│ └── skill-four/SKILL.mdName Collision Detection
No Duplicate Skill Names Within Marketplace
What to check: The skill's name field (from YAML frontmatter) does not match any other skill's name in the same marketplace.
How to verify: 1. Build the skill index (see above) 2. For each new or renamed skill, check if its name appears in any other plugin's skills 3. Skills within the same plugin can share a name with skills in other plugins only if the marketplace uses plugin:skill namespacing — but identical names are still confusing and should be flagged
Why it matters: Name collisions cause ambiguous skill references. When a user or automation references skill-name, the runtime may pick the wrong one or fail entirely.
Severity: Critical — a name collision means the skill cannot be reliably referenced.
Common false positives:
- A skill being moved between plugins (same name, different location) — check the diff to see if the old location was deleted. If so, this is a move, not a collision.
- Skills in different marketplaces (different repos) can share names without collision.
Plugin Manifest Consistency
plugin.json Exists and Is Valid
What to check: The plugin directory containing the new/changed skill has a valid plugin.json with at minimum: name, description, version.
How to verify: Read plugin.json from the plugin's .claude-plugin/ directory (or root, depending on marketplace convention). Verify it parses as valid JSON and contains the required fields.
Why it matters: A skill without a valid parent plugin.json won't be discovered by the marketplace runtime.
Severity: Critical if plugin.json is missing or invalid JSON. Major if required fields are missing.
Skill Directory Matches Plugin Structure
What to check: The new skill is placed in the plugin's skills/ directory following the marketplace's directory convention.
How to verify: Confirm: 1. The skill directory is inside <plugin_root>/skills/<skill_name>/ 2. The directory name matches the skill's name field in frontmatter 3. SKILL.md is at the root of the skill directory (not nested deeper)
Why it matters: Skills placed outside the expected directory structure won't be discovered by the plugin loader.
Severity: Critical if the skill is in the wrong location. Minor if the directory name doesn't match the frontmatter name (the runtime uses the frontmatter name, but mismatches cause confusion).
Cross-Reference Validation (Should-Have)
SKILL.md References Resolve to Existing Files
What to check: Every relative markdown link in SKILL.md ([text](path)) points to a file that exists within the skill directory.
How to verify: Parse markdown links from SKILL.md. For each relative path, check that the target file exists. Ignore:
- External URLs (
http://,https://) - Anchor links (
#section-name) - Links to files outside the skill directory (these are cross-skill references and may be valid)
Why it matters: Broken references mean the agent can't load the referenced content, resulting in incomplete skill execution.
Severity: Minor — the skill still loads, but loses access to referenced material.
Common false positives: Links to files that will be created by the same PR but are in a different commit — check the full PR diff, not just the current commit.
Trigger Keyword Overlap (Should-Have)
Flag Significant Overlap with Existing Skills
What to check: The new skill's description doesn't share the same primary trigger keywords as an existing skill in the marketplace to the point where the agent would have difficulty choosing between them.
How to verify: 1. Extract key terms from the new skill's description (nouns, verbs, technology names) 2. Compare against descriptions of all existing skills in the marketplace 3. Flag if two skills share 3+ primary trigger keywords AND their capability statements don't clearly differentiate them
Why it matters: When multiple skills match the same trigger, the agent may pick the wrong one or waste context loading both. Clear differentiation in descriptions prevents this.
Severity: Informational — overlap may be intentional (complementary skills) or the skill author may want to adjust their description.
Common false positives:
- Skills in the same domain that intentionally complement each other (e.g.,
review-pythonandpytest-code-reviewboth mention Python) - Skills that share technology keywords but serve different purposes (e.g., a "build" skill and a "review" skill for the same framework)
Script Quality (Should-Have)
Scripts Declare --help
What to check: If the skill includes executable scripts (.py, .sh, .js, etc.) in a scripts/ directory, each script supports a --help flag that describes its usage.
How to verify: Check script files for argument parsing that includes help text. Look for argparse, click, --help handling, or usage strings.
Why it matters: The agent uses --help output to understand how to invoke scripts correctly. Without it, the agent must read the full script source to determine usage, consuming unnecessary context.
Severity: Informational — scripts work without --help, but discoverability suffers.
Scripts Avoid Interactive Prompts
What to check: Scripts do not use input(), readline, read -p, or other TTY-dependent prompts. Agent environments typically don't support interactive input.
How to verify: Search script files for interactive input patterns:
- Python:
input(,sys.stdin.readwithout piped input - Bash:
read -p,select - Node:
readline,prompt
Why it matters: Interactive prompts hang in non-TTY agent environments, causing the skill to stall indefinitely.
Severity: Major if the script is part of the main workflow. Informational if it's an optional utility.
Structural Checks
All structural checks emit HIGH confidence issues. These are mechanically verifiable — the skill either passes or fails each check.
YAML Frontmatter
Valid YAML
What to check: The frontmatter block between --- delimiters parses as valid YAML. No tabs (YAML requires spaces), no unclosed quotes, no duplicate keys.
How to verify: Attempt to parse the frontmatter. Check for common YAML errors: tab characters, unquoted strings with special characters (:, #, {, }), missing closing quotes.
Why it matters: Invalid frontmatter prevents the skill from loading entirely. The agent never sees the skill.
Common false positives: Colons inside quoted description strings are valid YAML — description: "Use when: X happens" is fine.
Required Fields Present
What to check: Frontmatter contains both name and description fields with non-empty values.
How to verify: After parsing YAML, confirm both keys exist and their values are non-empty strings (not null, not empty string, not whitespace-only).
Why it matters: name and description are the only fields the runtime reads at startup for skill discovery. Without them, the skill is invisible.
Common false positives: None. These fields are unconditionally required.
Name Field
Kebab-Case Format
What to check: name contains only lowercase letters, numbers, and hyphens. No underscores, no uppercase, no spaces, no special characters.
How to verify: Match against pattern ^[a-z0-9]+(-[a-z0-9]+)*$.
Why it matters: The name is used as a directory name and as the skill identifier in plugin:skill references. Non-kebab names cause lookup failures.
Common false positives: None. The format is strictly defined.
Maximum Length
What to check: name is at most 64 characters.
How to verify: Count characters in the name string.
Why it matters: The runtime enforces this limit. Names exceeding 64 characters are silently truncated or rejected depending on the host.
Common false positives: None. This is a hard limit.
Reserved Words
What to check: name does not contain the substrings anthropic or claude (case-insensitive).
How to verify: Case-insensitive substring search.
Why it matters: These are reserved by Anthropic. Skills using reserved words may conflict with official skills or be rejected by marketplace policies.
Common false positives: A skill legitimately about Claude API integration might use claude-api — but the convention is to use descriptive names like api-client or llm-integration instead. Flag it but note the context.
Description Field
Maximum Length
What to check: description is at most 1024 characters.
How to verify: Count characters in the description string.
Why it matters: The runtime enforces this limit. Longer descriptions are truncated, potentially losing the "when to use" component that drives trigger accuracy.
Common false positives: None. This is a hard limit.
Third Person Voice
What to check: Description does not use first person ("I can", "I will", "I help") or second person ("You can", "You should", "Helps you").
How to verify: Check for pronouns I, my, me, you, your as word boundaries at the start of sentences or after periods. The description should read as a capability statement: "Processes X", "Reviews Y", "Generates Z".
Why it matters: Descriptions are injected into the system prompt alongside many other skill descriptions. Mixed point-of-view confuses the agent's skill selection. Third person is the convention across all skill ecosystems.
Common false positives: Quoted text within the description (e.g., Use when user says "I need help") — the pronouns are in quoted speech, not the description's own voice.
What and When Components
What to check: Description includes both what the skill does (capability) and when to use it (trigger conditions). Look for patterns like "Use when", "Triggers on", "Use for", or equivalent phrasing that separates capability from activation context.
How to verify: The description should have two distinct components. A description that only states capability ("Reviews Python code") without trigger context ("Use when reviewing .py files or checking type hints") is incomplete.
Why it matters: The description is the primary signal the agent uses for skill selection. Without "when" context, the agent either over-triggers (selects the skill for unrelated tasks) or under-triggers (misses relevant tasks).
Common false positives: Very short descriptions that pack both components into one clause — "Reviews Python code for type safety and async patterns" implicitly covers "when" (when there's Python code to review). Flag only when trigger context is genuinely absent.
SKILL.md Body
Line Limit
What to check: The SKILL.md file (including frontmatter) is under 500 lines.
How to verify: Count total lines in the file.
Why it matters: Once loaded, the entire SKILL.md competes for context window space. Beyond 500 lines, the skill degrades agent performance. Content should be split into reference files using progressive disclosure.
Common false positives: None. This is a hard limit from Anthropic's guidance.
File Structure
Reference Depth
What to check: Reference files linked from SKILL.md do not themselves link to further reference files (no chains). All references should be one level deep from SKILL.md.
How to verify: For each file referenced in SKILL.md, scan that file for markdown links to other files within the skill directory. If found, flag the chain.
Why it matters: The agent may only partially read nested references (using head -100 instead of full reads), resulting in incomplete information. One-level references ensure complete reads.
Common false positives: Links to external URLs (not local files) are fine. Links to files outside the skill directory (e.g., to other skills or project docs) are not reference chains — they're external references and should not be flagged here.
No Windows-Style Paths
What to check: No file paths in any skill file use backslash separators (\).
How to verify: Search all files in the skill directory for \ in contexts that look like file paths (adjacent to /, .md, .py, directory names).
Why it matters: Backslash paths break on Unix systems where most agents run. Forward slashes work on all platforms.
Common false positives: Backslashes in regex patterns, escape sequences in code blocks, or YAML escape characters. Only flag backslashes that are clearly file path separators.
Content Freshness
No Time-Sensitive Content
What to check: Skill files do not contain hardcoded dates, or relative time references like "recently", "new", "currently", "as of", "just released", "latest version".
How to verify: Search for:
- Date patterns:
20[0-9]{2}, month names adjacent to years - Relative time words:
recently,new(as in "new feature"),currently,as of,just released,latest
Why it matters: Skills persist across time. "The new API" becomes "the old API" silently. "As of 2025" becomes stale by 2026. Content should describe the current state without temporal anchoring.
Common false positives:
- Version numbers that happen to contain year-like patterns (
v2024.1) - The word "new" in technical context ("create a new file", "new instance")
- Dates in example output templates (showing what output looks like, not making temporal claims)
Use judgment: flag temporal claims about the external world, not incidental use of date-like patterns.