From 60c57a94cbef3dd0ff5d43949c915f3752746315 Mon Sep 17 00:00:00 2001 From: minsoo-web Date: Sun, 1 Mar 2026 19:42:08 +0900 Subject: [PATCH] feat: add skill-review plugin MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a new `skill-review` plugin that provides a slash-command for reviewing any SKILL.md against Claude Agent Skills best practices. The skill produces a structured Markdown report with per-check pass/fail status (37 checks across 8 categories), severity levels (error/warning/pass), and prioritized recommendations — enabling quality gates before merging skills into the marketplace. Co-Authored-By: Claude Sonnet 4.6 --- .../skill-review/.claude-plugin/plugin.json | 13 ++ plugins/skill-review/README.md | 82 ++++++++++++ .../skill-review/skills/skill-review/SKILL.md | 68 ++++++++++ .../skill-review/references/checklist.md | 118 ++++++++++++++++++ 4 files changed, 281 insertions(+) create mode 100644 plugins/skill-review/.claude-plugin/plugin.json create mode 100644 plugins/skill-review/README.md create mode 100644 plugins/skill-review/skills/skill-review/SKILL.md create mode 100644 plugins/skill-review/skills/skill-review/references/checklist.md diff --git a/plugins/skill-review/.claude-plugin/plugin.json b/plugins/skill-review/.claude-plugin/plugin.json new file mode 100644 index 0000000..837c377 --- /dev/null +++ b/plugins/skill-review/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "skill-review", + "version": "1.0.0", + "description": "Slash-command skill that reviews any SKILL.md against best practices and outputs a structured pass/fail report", + "author": { + "name": "minsoo.web", + "github": "minsoo-web" + }, + "category": "developer-tools", + "license": "MIT", + "keywords": ["skill", "review", "linter", "best-practices", "quality", "marketplace"], + "skills": "./skills/" +} diff --git a/plugins/skill-review/README.md b/plugins/skill-review/README.md new file mode 100644 index 0000000..5a9ed80 --- /dev/null +++ b/plugins/skill-review/README.md @@ -0,0 +1,82 @@ +# skill-review + +> Slash-command skill that reviews any SKILL.md against best practices and outputs a structured pass/fail report + +## Installation + +```bash +claude plugin install skill-review@hamsurang/hamkit +``` + +## What This Plugin Does + +The `skill-review` plugin adds a slash-command that reviews any `SKILL.md` against the Claude Agent Skills best practices. It produces a structured Markdown report with per-check pass/fail status, severity levels, and prioritized recommendations — so you can catch quality issues before merging a skill into the marketplace. + +## Activation + +Use the skill with an explicit path or let it auto-discover: + +``` +/skill-review plugins/my-skill/skills/my-skill/SKILL.md +/skill-review # auto-discovers SKILL.md in current dir +``` + +Also activates when you say: +- "review this skill" +- "skill review" +- "check my SKILL.md" +- "review the skill at ..." + +## What Gets Checked + +| Category | Examples | +|---|---| +| Frontmatter | Name format, character limits, reserved words, no XML tags | +| Description quality | Third-person, "Use when..." form, specific triggers, no workflow summary | +| Naming conventions | Gerund preferred, not vague generics | +| Content quality | ≤500 lines, imperative form, no explaining basics, runnable examples | +| Progressive disclosure | Heavy reference in `references/`, one-level nesting, ToC for large files | +| Structure | Unix paths, no stale dates, descriptive file names | +| Scripts (if present) | Error handling, no magic numbers, documented dependencies, qualified MCP names | +| Plugin manifest (if present) | Required fields in `plugin.json` | + +## Output Format + +```markdown +## Skill Review: [skill-name] + +### Summary +**Status:** PASS / NEEDS WORK / FAIL +**Score:** N/N checks passed | N warnings | N errors + +### ✅ Passed (N) +... + +### ⚠️ Warnings (N) +- **[Check name]**: [finding] — [why it matters] + +### ❌ Errors (N) +- **[Check name]**: [finding] — [why it must be fixed] + +### 📋 Prioritized Recommendations +1. Most critical fix first +... +``` + +## Plugin Structure + +``` +skill-review/ +├── .claude-plugin/ +│ └── plugin.json # Plugin manifest +├── skills/ +│ └── skill-review/ +│ ├── SKILL.md # Activation conditions + review workflow +│ └── references/ +│ └── checklist.md # Full review rubric (37 checks) +└── README.md +``` + +## License + +MIT diff --git a/plugins/skill-review/skills/skill-review/SKILL.md b/plugins/skill-review/skills/skill-review/SKILL.md new file mode 100644 index 0000000..2bbd5c0 --- /dev/null +++ b/plugins/skill-review/skills/skill-review/SKILL.md @@ -0,0 +1,68 @@ +--- +name: skill-review +description: > + Use when reviewing a skill file for quality before publishing, merging, or deploying to + a marketplace. Triggers on "review this skill", "skill review", "check my SKILL.md", + "review the skill at [path]", or when the user wants structured feedback on whether a + skill meets best practices. +--- + +# Skill Review + +Reviews a `SKILL.md` against established best practices and outputs a structured pass/fail report with prioritized recommendations. + +## Locating the Target Skill + +**With explicit path:** Use the provided path directly (supports both `SKILL.md` files and plugin directories). + +**Without path — search in this order:** + +1. Current directory: `./SKILL.md` +2. Plugin skill dirs: `./plugins/*/skills/*/SKILL.md` +3. Prompt the user if multiple matches found + +## Review Workflow + +1. Read `SKILL.md` and any files in `references/` that it links to +2. Run each check in `references/checklist.md` — assign PASS ✅, WARNING ⚠️, or ERROR ❌ +3. Output the structured report below + +Be educational, not just a linter — include a brief explanation of *why* each finding matters. + +## Output Format + +~~~markdown +## Skill Review: [skill-name] + +### Summary +**Status:** PASS / NEEDS WORK / FAIL +**Score:** N/N checks passed | N warnings | N errors + +### ✅ Passed (N) +- [Check description] +- ... + +### ⚠️ Warnings (N) +- **[Check name]**: [finding] — [brief explanation of why it matters] +- ... + +### ❌ Errors (N) +- **[Check name]**: [finding] — [why it must be fixed before publishing] +- ... + +### 📋 Prioritized Recommendations +1. [Most critical fix first] +2. ... +~~~ + +## Severity Definitions + +| Severity | Meaning | +|---|---| +| ❌ Error | Violates a spec requirement. Must fix before publishing. | +| ⚠️ Warning | Best practice violation. Should fix for quality. | +| ✅ Pass | Meets the standard. | + +## Full Rubric + +See `references/checklist.md` for all checks organized by category (frontmatter, description quality, naming, content, structure, scripts, plugin manifest). diff --git a/plugins/skill-review/skills/skill-review/references/checklist.md b/plugins/skill-review/skills/skill-review/references/checklist.md new file mode 100644 index 0000000..32caae8 --- /dev/null +++ b/plugins/skill-review/skills/skill-review/references/checklist.md @@ -0,0 +1,118 @@ +# Skill Review Checklist + +Derived from the Claude Agent Skills best practices. Run every check against the target `SKILL.md`. + +--- + +## 1. Frontmatter + +| Check | Severity | What to look for | +|---|---|---| +| Only `name` and `description` fields present | ⚠️ Warning | Extra fields (e.g. `version`, `license`) are ignored by Claude and signal authoring confusion | +| Total frontmatter ≤ 1024 characters | ❌ Error | Longer frontmatter may be truncated; description becomes unreliable | +| `name` uses only letters, numbers, and hyphens | ❌ Error | Parentheses, underscores, or special characters break skill lookup | +| No XML/HTML tags in frontmatter values | ❌ Error | Tags cause parsing errors in some environments | +| `name` value is not a reserved word | ❌ Error | Avoid: `help`, `skills`, `cancel`, `clear`, `reset` | + +--- + +## 2. Description Quality + +The description is how Claude decides whether to load a skill. It must be a precise triggering signal. + +| Check | Severity | What to look for | +|---|---|---| +| Written in third person | ❌ Error | "Use when..." not "I help you..." or "You can use this..." — it is injected into the system prompt | +| Describes ONLY triggering conditions, NOT workflow | ❌ Error | Summarizing the skill's process in the description causes Claude to follow the description instead of reading the full skill | +| Starts with "Use when..." | ⚠️ Warning | Strongly preferred; makes triggering intent unambiguous | +| Includes specific trigger phrases or keywords | ❌ Error | Vague descriptions ("helps with skills") cause missed activations | +| Includes "what" context AND "when to use" context | ⚠️ Warning | Pure "what" without "when" creates confusion; pure "when" without domain context may match too broadly | +| No vague generics like "helps with", "assists in" | ⚠️ Warning | Weak phrasing degrades retrieval precision | +| Description ≤ 500 characters (not counting YAML key) | ⚠️ Warning | Longer descriptions risk truncation and are harder to scan | +| Technology-specific triggers are explicit | ⚠️ Warning | If the skill is framework-specific, say so ("Use when using React Router...") | + +--- + +## 3. Naming Conventions + +| Check | Severity | What to look for | +|---|---|---| +| Name uses gerund (-ing) or descriptive verb form for process skills | ⚠️ Warning | `creating-skills` > `skill-creation`; `condition-based-waiting` > `async-test-helpers` | +| Name is not a vague generic | ⚠️ Warning | Avoid: `helper`, `utils`, `misc`, `tools` — names must be searchable | +| Name reflects the action being taken, not the domain | ⚠️ Warning | `root-cause-tracing` > `debugging` — concrete > abstract | + +--- + +## 4. Content Quality + +| Check | Severity | What to look for | +|---|---|---| +| Skill body is ≤ 500 lines | ⚠️ Warning | Longer skills should move heavy reference to `references/` files | +| Instructions use imperative form | ⚠️ Warning | "Read the config file" not "You should read the config file" | +| No explaining what Claude already knows | ⚠️ Warning | Skip basics like "Markdown is a markup language" — focus on non-obvious context | +| Consistent terminology throughout | ⚠️ Warning | Pick one term per concept; don't swap between "test" / "spec" / "case" arbitrarily | +| One high-quality example (not mediocre multi-language examples) | ⚠️ Warning | One complete, runnable, well-commented example beats five generic stubs | +| No narrative storytelling ("In session X, we found...") | ❌ Error | Skills must be reusable across contexts, not session-specific post-mortems | +| Code examples are complete and runnable | ⚠️ Warning | Fill-in-the-blank templates are nearly useless | + +--- + +## 5. Progressive Disclosure + +| Check | Severity | What to look for | +|---|---|---| +| Heavy reference (100+ lines) is in `references/` not inline | ⚠️ Warning | Inline API docs bloat every invocation of the skill | +| Nesting is at most one level deep (`references/topic.md`) | ⚠️ Warning | Deeper nesting (`references/a/b/c.md`) is hard to maintain and discover | +| If the skill has ≥ 4 major sections, there is a table of contents | ⚠️ Warning | Long skills without a ToC are hard to navigate | +| `references/` files are only loaded when relevant (lazy loading) | ⚠️ Warning | "Load all reference files upfront" wastes context; files should be conditional | + +--- + +## 6. Structure & File Hygiene + +| Check | Severity | What to look for | +|---|---|---| +| All file paths use Unix format (forward slashes) | ❌ Error | Windows-style paths (`references\checklist.md`) break cross-platform skills | +| No time-sensitive information (dates, version numbers without caveats) | ⚠️ Warning | Skills are reused long-term; stale dates erode trust | +| Separate files have descriptive names (not `file1.md`, `helper.js`) | ⚠️ Warning | File names must convey purpose to future readers | +| Supporting files only exist for reusable tools or heavy reference | ⚠️ Warning | One-off content should stay inline | +| Flowcharts are only used for non-obvious decisions or process loops | ⚠️ Warning | Flowcharts for linear instructions or reference material add noise | + +--- + +## 7. Scripts (if present) + +Only applies if the skill includes shell scripts, Python scripts, or other executable files. + +| Check | Severity | What to look for | +|---|---|---| +| Scripts have explicit error handling | ❌ Error | Silent failures in skill scripts are very hard to debug | +| No magic numbers without explanation | ⚠️ Warning | Constants like `60`, `1024`, `0x1F` must be named or commented | +| All required packages/dependencies are documented | ❌ Error | Scripts that depend on unlisted packages fail silently on other machines | +| MCP tool calls use fully qualified names (`mcp__server__tool`) | ❌ Error | Unqualified MCP names fail when multiple servers are loaded | + +--- + +## 8. Plugin Manifest (if present) + +Only applies if the skill is part of a plugin (includes `plugin.json`). + +| Check | Severity | What to look for | +|---|---|---| +| `plugin.json` has `name` field | ❌ Error | Required for plugin registry | +| `plugin.json` has `version` field (semver) | ❌ Error | Required for update management | +| `plugin.json` has `description` field | ❌ Error | Required for marketplace display | +| `plugin.json` has `author` field | ⚠️ Warning | Strongly recommended for attribution and support | +| `plugin.json` has `category` field | ⚠️ Warning | Required for marketplace categorization | + +--- + +## Scoring Guide + +After running all checks: + +| Result | Status | +|---|---| +| 0 errors, 0 warnings | **PASS** — ready to publish | +| 0 errors, 1+ warnings | **NEEDS WORK** — fix warnings before merging | +| 1+ errors | **FAIL** — must fix errors before publishing |