skill-forge-review

Name: skill-forge-review
Author: AgriciDaniel

78stars33forks

How to install skill-forge-review?

agricidaniel/skill-forge/skill-forge-review

$npx -y skills add AgriciDaniel/skill-forge --skill skill-forge-review

Installs into the current project.

Summary

Audit and validate existing Claude Code skills for quality, triggering accuracy, structure compliance, and best practices. Scores skills on a 0-100 scale and provides prioritized improvement recommendations. Use when user says "review skill", "audit skill", "check skill", "valida

Files · 1

View on GitHub

SKILL.md

1	# Skill Review & Validation
2
3	## Process
4
5	### Step 1: Locate Skill Files
6
7	Accept input as:
8	- Path to a skill directory
9	- Skill name (search in `~/.claude/skills/`)
10	- URL to a GitHub repository
11
12	Read all `.md` files, scripts, and asset files.
13
14	### Step 2: Structure Validation
15
16	Run `python scripts/validate_skill.py <path>` for programmatic checks.
17
18	Manual verification:
19	- [ ] SKILL.md exists (exact case)
20	- [ ] No README.md inside skill folder
21	- [ ] Folder name matches `name` field
22	- [ ] Valid kebab-case naming (1-64 chars)
23	- [ ] No "claude" or "anthropic" in name
24
25	### Step 3: Frontmatter Audit
26
27	\| Check \| Pass Criteria \|
28	\|-------\|--------------\|
29	\| Name format \| kebab-case, 1-64 chars, no leading/trailing hyphens \|
30	\| Description present \| Non-empty, 1-1024 characters \|
31	\| Description has WHAT \| Explains capabilities \|
32	\| Description has WHEN \| Includes trigger phrases \|
33	\| Description has keywords \| Domain-specific terms included \|
34	\| No XML tags \| No < or > characters \|
35	\| Optional fields valid \| license, compatibility (<500 chars), metadata \|
36
37	### Step 4: Triggering Analysis
38
39	Assess the description for activation quality:
40
41	Under-triggering risks:
42	- Too generic ("Helps with projects")
43	- Missing common paraphrases
44	- No domain keywords
45	- Missing file type mentions (if relevant)
46
47	Over-triggering risks:
48	- Too broad ("Processes documents")
49	- Overlaps with built-in Claude capabilities
50	- Missing negative triggers for disambiguation
51
52	Generate test queries:
53	- 5 queries that SHOULD trigger the skill
54	- 5 queries that SHOULD NOT trigger
55	- 3 edge cases (ambiguous queries)
56
57	### Step 5: Instruction Quality
58
59	\| Criterion \| Score (0-10) \|
60	\|-----------\|-------------\|
61	\| Specificity \| Are instructions actionable? (not "validate properly") \|
62	\| Completeness \| All workflows covered? \|
63	\| Error handling \| Common failures addressed? \|
64	\| Examples \| Concrete examples provided? \|
65	\| Progressive disclosure \| Detailed docs in references/ not SKILL.md? \|
66	\| Length \| Under 500 lines / 5000 tokens? \|
67	\| Cross-references \| Clear links to references/scripts? \|
68
69	### Step 6: Architecture Review (Multi-skill)
70
71	For skills with sub-skills:
72	- [ ] Main skill has clear routing table
73	- [ ] Sub-skills have focused responsibilities
74	- [ ] Cross-references are valid (files exist)
75	- [ ] Naming follows `parent-child` convention
76	- [ ] Shared references in parent, not duplicated
77	- [ ] Agents have clear roles (if Tier 4)
78
79	### Step 7: Script Quality (if present)
80
81	- [ ] Docstrings with purpose, input, output
82	- [ ] CLI interface (argparse or similar)
83	- [ ] Structured output (JSON)
84	- [ ] Error handling (try/except with clear messages)
85	- [ ] No hardcoded paths or secrets
86	- [ ] Minimal dependencies
87
88	### Step 8: Generate Skill Health Score
89
90	Scoring methodology (0-100):
91
92	\| Category \| Weight \| Checks \|
93	\|----------\|--------\|--------\|
94	\| Frontmatter Quality \| 25% \| Name, description, format \|
95	\| Trigger Accuracy \| 20% \| WHAT + WHEN + keywords \|
96	\| Instruction Quality \| 25% \| Specificity, completeness, examples \|
97	\| Structure Compliance \| 15% \| File naming, organization, references \|
98	\| Script Quality \| 10% \| If applicable (full marks if no scripts needed) \|
99	\| Progressive Disclosure \| 5% \| Proper use of 3-level system \|
100
101	### Step 9: Generate Trigger Eval Set
102
103	After reviewing, generate a structured trigger eval set for ongoing testing:
104
105	1. Run `python scripts/generate_eval_set.py <path>` to auto-generate a starter set
106	2. Review and refine the generated queries:
107	- Ensure 8-10 should-trigger queries cover different phrasings and edge cases
108	- Ensure 8-10 should-not-trigger queries are near-misses (not obviously irrelevant)
109	- Include casual speech, typos, and uncommon domain uses in should-trigger set
110	3. Save the eval set to `evals/evals.json` in the skill directory
111
112	Good queries are realistic and specific (include file paths, context, domain details).
113	Bad queries are overly generic ("format this data") or obviously irrelevant.
114
115	4. Run `python scripts/optimize_description.py <path> --eval-set evals/evals.json`
116	to score the current description and get improvement suggestions
117	5. Recommend running `/skill-forge eval <path>` for full functional evaluation
118
119	### Step 10: Generate Report
120
121	```markdown
122	# Skill Review: [name]
123
124	## Health Score: [X]/100
125
126	## Summary
127	[2-3 sentence assessment]
128
129	## Scores by Category
130	\| Category \| Score \| Notes \|
131	\|----------\|-------\|-------\|
132	\| Frontmatter \| X/25 \| [issues] \|
133	\| Triggering \| X/20 \| [issues] \|
134	\| Instructions \| X/25 \| [issues] \|
135	\| Structure \| X/15 \| [issues] \|
136	\| Scripts \| X/10 \| [issues] \|
137	\| Disclosure \| X/5 \| [issues] \|
138
139	## Critical Issues (fix immediately)
140	- [issue 1]

People who liked this also viewed

6 picks

Type

skill-forge-review

78stars33forks

View on GitHub

How to install skill-forge-review?

agricidaniel/skill-forge/skill-forge-review

$npx -y skills add AgriciDaniel/skill-forge --skill skill-forge-review

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Skill Review & Validation
2
3	## Process
4
5	### Step 1: Locate Skill Files
6
7	Accept input as:
8	- Path to a skill directory
9	- Skill name (search in `~/.claude/skills/`)
10	- URL to a GitHub repository
11
12	Read all `.md` files, scripts, and asset files.
13
14	### Step 2: Structure Validation
15
16	Run `python scripts/validate_skill.py <path>` for programmatic checks.
17
18	Manual verification:
19	- [ ] SKILL.md exists (exact case)
20	- [ ] No README.md inside skill folder
21	- [ ] Folder name matches `name` field
22	- [ ] Valid kebab-case naming (1-64 chars)
23	- [ ] No "claude" or "anthropic" in name
24
25	### Step 3: Frontmatter Audit
26
27	\| Check \| Pass Criteria \|
28	\|-------\|--------------\|
29	\| Name format \| kebab-case, 1-64 chars, no leading/trailing hyphens \|
30	\| Description present \| Non-empty, 1-1024 characters \|
31	\| Description has WHAT \| Explains capabilities \|
32	\| Description has WHEN \| Includes trigger phrases \|
33	\| Description has keywords \| Domain-specific terms included \|
34	\| No XML tags \| No < or > characters \|
35	\| Optional fields valid \| license, compatibility (<500 chars), metadata \|
36
37	### Step 4: Triggering Analysis
38
39	Assess the description for activation quality:
40
41	Under-triggering risks:
42	- Too generic ("Helps with projects")
43	- Missing common paraphrases
44	- No domain keywords
45	- Missing file type mentions (if relevant)
46
47	Over-triggering risks:
48	- Too broad ("Processes documents")
49	- Overlaps with built-in Claude capabilities
50	- Missing negative triggers for disambiguation
51
52	Generate test queries:
53	- 5 queries that SHOULD trigger the skill
54	- 5 queries that SHOULD NOT trigger
55	- 3 edge cases (ambiguous queries)
56
57	### Step 5: Instruction Quality
58
59	\| Criterion \| Score (0-10) \|
60	\|-----------\|-------------\|
61	\| Specificity \| Are instructions actionable? (not "validate properly") \|
62	\| Completeness \| All workflows covered? \|
63	\| Error handling \| Common failures addressed? \|
64	\| Examples \| Concrete examples provided? \|
65	\| Progressive disclosure \| Detailed docs in references/ not SKILL.md? \|
66	\| Length \| Under 500 lines / 5000 tokens? \|
67	\| Cross-references \| Clear links to references/scripts? \|
68
69	### Step 6: Architecture Review (Multi-skill)
70
71	For skills with sub-skills:
72	- [ ] Main skill has clear routing table
73	- [ ] Sub-skills have focused responsibilities
74	- [ ] Cross-references are valid (files exist)
75	- [ ] Naming follows `parent-child` convention
76	- [ ] Shared references in parent, not duplicated
77	- [ ] Agents have clear roles (if Tier 4)
78
79	### Step 7: Script Quality (if present)
80
81	- [ ] Docstrings with purpose, input, output
82	- [ ] CLI interface (argparse or similar)
83	- [ ] Structured output (JSON)
84	- [ ] Error handling (try/except with clear messages)
85	- [ ] No hardcoded paths or secrets
86	- [ ] Minimal dependencies
87
88	### Step 8: Generate Skill Health Score
89
90	Scoring methodology (0-100):
91
92	\| Category \| Weight \| Checks \|
93	\|----------\|--------\|--------\|
94	\| Frontmatter Quality \| 25% \| Name, description, format \|
95	\| Trigger Accuracy \| 20% \| WHAT + WHEN + keywords \|
96	\| Instruction Quality \| 25% \| Specificity, completeness, examples \|
97	\| Structure Compliance \| 15% \| File naming, organization, references \|
98	\| Script Quality \| 10% \| If applicable (full marks if no scripts needed) \|
99	\| Progressive Disclosure \| 5% \| Proper use of 3-level system \|
100
101	### Step 9: Generate Trigger Eval Set
102
103	After reviewing, generate a structured trigger eval set for ongoing testing:
104
105	1. Run `python scripts/generate_eval_set.py <path>` to auto-generate a starter set
106	2. Review and refine the generated queries:
107	- Ensure 8-10 should-trigger queries cover different phrasings and edge cases
108	- Ensure 8-10 should-not-trigger queries are near-misses (not obviously irrelevant)
109	- Include casual speech, typos, and uncommon domain uses in should-trigger set
110	3. Save the eval set to `evals/evals.json` in the skill directory
111
112	Good queries are realistic and specific (include file paths, context, domain details).
113	Bad queries are overly generic ("format this data") or obviously irrelevant.
114
115	4. Run `python scripts/optimize_description.py <path> --eval-set evals/evals.json`
116	to score the current description and get improvement suggestions
117	5. Recommend running `/skill-forge eval <path>` for full functional evaluation
118
119	### Step 10: Generate Report
120
121	```markdown
122	# Skill Review: [name]
123
124	## Health Score: [X]/100
125
126	## Summary
127	[2-3 sentence assessment]
128
129	## Scores by Category
130	\| Category \| Score \| Notes \|
131	\|----------\|-------\|-------\|
132	\| Frontmatter \| X/25 \| [issues] \|
133	\| Triggering \| X/20 \| [issues] \|
134	\| Instructions \| X/25 \| [issues] \|
135	\| Structure \| X/15 \| [issues] \|
136	\| Scripts \| X/10 \| [issues] \|
137	\| Disclosure \| X/5 \| [issues] \|
138
139	## Critical Issues (fix immediately)
140	- [issue 1]

People who liked this also viewed

6 picks

Type