Skip to content

existential-birds/beagle / plugins/beagle-core/skills/review-skill

review-skill

Verified

Reviews PRs that add or modify Agent Skills, checking structural validity, design quality, and marketplace consistency. Use when reviewing skill file changes, auditing SKILL.md quality, or running automated skill PR reviews.

FileKindSize
SKILL.mdskill md5.8 KB
references/design-checks.mdmarkdown9.0 KB
references/marketplace-checks.mdmarkdown7.3 KB
references/structural-checks.mdmarkdown7.6 KB

references/design-checks.md

View on GitHub
# 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:**
```yaml
# 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:**
```yaml
# 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 practices
```

**When 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:**
```markdown
# 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:**
```markdown
# 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:**
```markdown
# 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:**
```markdown
# 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

```markdown
## Summary
[1-2 sentences]

## Findings
1. [FILE:LINE] TITLE
   - Issue: ...
   - Fix: ...
```
````

**Bad pattern:**
```markdown
## 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")
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall