From 67baac0acb6043bf0ae15bb621e785b63e6f11ba Mon Sep 17 00:00:00 2001 From: Gordon Bockus Date: Wed, 11 Mar 2026 16:07:31 -0500 Subject: [PATCH] chore: Add skill for reviewing skills in repo against best practices --- .../rules/reviewing-skill-best-practices.mdc | 175 ++++++++++++++++++ .gitignore | 1 - README.md | 12 ++ 3 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 .cursor/rules/reviewing-skill-best-practices.mdc diff --git a/.cursor/rules/reviewing-skill-best-practices.mdc b/.cursor/rules/reviewing-skill-best-practices.mdc new file mode 100644 index 0000000..a8e71cb --- /dev/null +++ b/.cursor/rules/reviewing-skill-best-practices.mdc @@ -0,0 +1,175 @@ +--- +description: Review and validate SKILL.md files against skill-best-practices.md. Use when asked to review a skill, audit a SKILL.md, check skill quality, validate skill structure, or run a skill best-practices review. Produces a consistent review report with numbered findings, severity ratings, and recommendations. +globs: **/SKILL.md, **/reviews/** +alwaysApply: false +--- + +# Reviewing Skill Best Practices + +## Goal + +Review a SKILL.md file against the documented best practices in `skill-best-practices.md` and produce a structured review report with numbered findings, severity ratings, and concrete recommendations. + +## Workflow + +### Step 1: Load the Best Practices Reference + +Read `skill-best-practices.md` from the repository root. This is the authoritative source for all review criteria. If the file is not found, stop and inform the user. + +### Step 2: Load the Target Skill + +Read the target SKILL.md file. Also inspect the skill's directory for supporting assets (`docs/`, `examples/`, `templates/`, `scripts/`, `references/`, `assets/`). Note which subdirectories exist and which are absent. + +### Step 3: Evaluate Against Review Criteria + +Assess the skill against every criterion below. Only report findings where the skill does not fully pass. + +#### 3a. Naming (Folder and Frontmatter) + +- Folder name uses gerund form (verb ending in "-ing") +- Folder name is lowercase with hyphens +- Frontmatter `name:` matches the folder name exactly +- Name is short, readable, and describes an action Vibes can execute + +#### 3b. Description (Frontmatter) + +- Roughly 100 words or fewer +- Leads with what the skill produces or the expected outcome +- Includes domain keywords relevant to the task +- Contains trigger phrases for when the skill should activate +- Describes results, not intentions +- Does not contain operational instructions or implementation details + +#### 3c. Core Instruction Sections + +Verify the presence and quality of all four required sections: + +- **Goal** — Explicit section defining the purpose +- **Workflow** — Logical, numbered or sequenced steps +- **Validation** — Checks that ensure outputs follow best practices +- **Output** — Explicit definition of the final artifact + +#### 3d. Progressive Disclosure + +- SKILL.md is under 500 lines +- Supporting material extracted into `docs/`, `examples/`, or `templates/` +- Core instructions remain focused on goal, workflow, validation, and output + +#### 3e. Directory Structure + +- Skill directory is one level deep (no deep nesting) +- Supporting files in recognized subdirectories (`docs/`, `examples/`, `templates/`, `scripts/`, `references/`, `assets/`) +- At least one supporting asset exists where content would benefit from it + +#### 3f. Context Efficiency + +- No unnecessary explanations or filler content +- Instructions are concise and directive +- No redundant or duplicated content blocks +- "When to Use" section does not simply repeat the frontmatter description + +#### 3g. Instructional Tone + +- Directive/imperative tone ("Ensure...", "Always...", "Never...") +- Reads as instructions *to Vibes*, not documentation *about a topic* + +#### 3h. Formatting + +- Heading hierarchy is consistent (no H1 inside H2, etc.) +- Markdown is well-formed (proper spacing, consistent list formatting) +- Capitalization is consistent throughout + +#### 3i. Metadata Completeness + +- Frontmatter includes `name` and `description` (required) +- Optional but recommended: `metadata.version`, `metadata.category`, `license`, `compatibility` + +#### 3j. Testing and Maintainability + +- Skill appears tested in realistic scenarios +- Instructions are modular and easy to update +- Skill is reusable across projects + +### Step 4: Assign Severity + +| Severity | Criteria | +|----------|----------| +| **High** | Violates a core best practice that impacts discoverability, activation, or output quality. Fix before merging. | +| **Medium** | Reduces quality or consistency but does not prevent the skill from functioning. Should be addressed. | +| **Low** | Cosmetic, minor efficiency, or nice-to-have improvement. | + +### Step 5: Categorize Each Finding + +Assign one of: Naming, Discovery, Structure, Architecture, Efficiency, Tone, Formatting, Metadata. + +### Step 6: Generate the Review Report + +Write the report using the exact format below. Order findings by severity (High first, then Medium, then Low). + +### Step 7: Identify Strengths + +Note what the skill does well. Include this in the Overall Assessment. + +## Validation + +Before finalizing, verify: +- Every finding includes a Best Practice Reference blockquote +- Every finding includes Current state, Recommendation, Reasoning, and Severity +- Findings are numbered sequentially with no gaps +- The summary table includes all findings +- The Overall Assessment acknowledges strengths, not just gaps + +## Output + +Save the report to `reviews/-skill-review.md`. + +## Report Template + +Every review report MUST follow this exact format: + +```markdown +# Skill Review: `/SKILL.md` + +Reviewed against: `skill-best-practices.md` + +--- + +## 1. — + +**Best Practice Reference:** +> + +**Current:** + +**Recommendation:** + +**Reasoning:** + +**Severity:** — + +--- + +(Repeat for each finding, numbered sequentially) + +--- + +## Summary + +| # | Finding | Severity | Category | +|---|---------|----------|----------| +| 1 | | <High/Medium/Low> | <category> | +| ... | ... | ... | ... | + +**Overall Assessment:** <2-3 sentences: acknowledge strengths first, summarize gaps, state what addressing findings would accomplish.> +``` + +### Report Rules + +1. Every finding MUST include a Best Practice Reference blockquote from `skill-best-practices.md`. +2. Recommendations MUST be specific — include example text, renamed values, or restructured sections. +3. Number findings sequentially with no gaps. +4. Use only `High`, `Medium`, or `Low` severity labels. +5. Use only these category labels: Naming, Discovery, Structure, Architecture, Efficiency, Tone, Formatting, Metadata. +6. Order findings by severity: High first, then Medium, then Low. +7. The summary table MUST include every finding. +8. The Overall Assessment MUST acknowledge at least one strength. diff --git a/.gitignore b/.gitignore index 78e4683..b84ea01 100644 --- a/.gitignore +++ b/.gitignore @@ -205,7 +205,6 @@ pnpm-lock.yaml scratch.txt notes.txt TODO.txt -.cursor/ .copilot/ # Test output diff --git a/README.md b/README.md index 63dc051..b23b7ae 100644 --- a/README.md +++ b/README.md @@ -453,6 +453,18 @@ To update an existing skill: 4. Validate using `skills-ref validate ./skills/<category>/<skill-name>` 5. Commit with clear message: `Update [skill-name]: [what changed]` +### Reviewing Skills Against Best Practices + +This repository includes a Cursor rule (`.cursor/rules/reviewing-skill-best-practices.mdc`) that automates skill quality reviews against the documented standards in `skill-best-practices.md`. Use it whenever you add a new skill or make significant changes to an existing one. + +To run a review, ask Cursor to **"review the `<skill-name>` skill"** while working in the repository. The rule will: + +1. Load `skill-best-practices.md` as the authoritative reference +2. Evaluate the target `SKILL.md` against criteria covering naming, description, core sections, directory structure, progressive disclosure, context efficiency, tone, formatting, and metadata +3. Produce a structured report in `reviews/<skill-folder-name>-skill-review.md` with numbered findings, severity ratings (High / Medium / Low), and actionable recommendations + +Review reports help catch common issues before pull requests — such as missing gerund naming, absent Validation or Output sections, description phrasing, and missing supporting assets. Address all **High** findings before merging and **Medium** findings when practical. + # Experimental