| name | skill-forge |
| version | 1 |
| description | Advanced skill creation and refinement pipeline. Wraps skill-creator with an automatic multi-criteria review loop that grades skills on quality, usefulness, alternatives analysis, and implementation — then iteratively improves until all criteria reach grade A, or stops after 10 loops with no further improvement. Use this skill whenever the user wants to create a high-quality, production-grade skill with rigorous self-review, or wants to upgrade/audit an existing skill to professional standards. Also triggers when the user says "tạo skill nâng cao", "forge a skill", "create and review skill", "auto-improve skill", "skill chất lượng cao", "nâng cấp skill", "review skill", "audit skill quality", or wants a skill that's been validated through multiple rounds of critical analysis rather than just a first draft.
|
Skill Forge — Advanced Skill Creator with Auto-Review Loop
Governance: Read and follow .github/RULE.md — it overrides all instructions below.
Skill Forge builds on top of skill-creator by adding a structured review-and-improve cycle. The idea is simple: creating a skill draft is only step one. What makes a skill genuinely useful is pressure-testing it from multiple angles — quality standards, real-world usefulness, alternative approaches, implementation rigor — and then systematically closing the gaps.
When This Skill Activates
Create mode — User wants a new skill:
- "Tạo skill mới cho X", "build me a skill for Y", "turn this into a polished skill"
- Forge creates the initial draft via skill-creator, then runs the review loop
Review/Update mode — User has an existing skill to improve:
- "Review skill này", "nâng cấp skill X", "audit this skill", "improve my skill"
- Forge reviews the existing skill, then iterates improvements
The key difference from plain skill-creator: Forge doesn't stop after one draft. It automatically evaluates, critiques, and refines — handling the "is this actually good?" question that usually requires human judgment.
The Forge Pipeline
┌─────────────────────────────────────────────────────────┐
│ SKILL FORGE PIPELINE │
│ │
│ 1. CREATE or LOAD skill (via skill-creator) │
│ 2. AUTO-REVIEW against 6 criteria (A/B/C/D grading) │
│ 3. ANALYZE alternatives — could this be done better? │
│ 4. SYNTHESIZE improvement plan from review findings │
│ 5. UPDATE skill (via skill-creator patterns) │
│ 6. RE-REVIEW — loop until all criteria ≥ A │
│ or 10 iterations with no score improvement → stop │
└─────────────────────────────────────────────────────────┘
Phase 1: Create or Load
New skill: Follow the skill-creator workflow — capture intent, interview, write SKILL.md. The goal here is a solid first draft, not perfection. Don't over-polish at this stage; the review loop handles refinement.
Existing skill: Read the SKILL.md and all bundled resources. Understand what the skill does, how it's structured, and what its current strengths/weaknesses are.
Phase 2: Auto-Review
This is the core of Forge. Evaluate the skill against six criteria, each graded A through D. The review should be honest and specific — vague "looks good" feedback helps no one.
Review Rubric
| # | Criterion | What It Measures |
|---|
| 1 | Skill Structure | Does the SKILL.md follow skill-creator conventions? Progressive disclosure, frontmatter, clear organization, appropriate length (<500 lines body) |
| 2 | Instruction Clarity | Are instructions explanatory (why, not just what)? Would a capable LLM follow them correctly without ambiguity? No excessive MUSTs/NEVERs without rationale |
| 3 | Real-World Usefulness | Does this skill solve a genuine problem users actually have? Is the trigger description accurate and comprehensive? Would a user be glad this skill exists? |
| 4 | Alternative Analysis | Has the space of solutions been explored? Could the same goal be achieved with existing tools, simpler approaches, or a different skill design? Is the current approach the best one? |
| 5 | Implementation Quality | Are scripts functional and well-organized? Error handling present where needed? Dependencies reasonable? Edge cases covered? |
| 6 | Description & Triggering | Is the description field optimized for triggering? Does it cover the right range of user phrasings without being too broad or too narrow? |
Grade Definitions
| Grade | Meaning | Action |
|---|
| A | Excellent — production-ready, no meaningful improvements possible | No changes needed for this criterion |
| B | Good — works well, minor polish opportunities | Improve if easy; acceptable to ship |
| C | Adequate — functional but has notable gaps | Needs improvement before shipping |
| D | Needs work — significant issues that undermine the skill's value | Must fix before proceeding |
How to Conduct the Review
For each criterion, produce:
criterion: "Skill Structure"
grade: "B"
evidence: |
- SKILL.md is 320 lines, well within limit
- Missing progressive disclosure: large reference block should move to references/
- Frontmatter description is present but could be more specific
strengths:
- Clean section organization
- Good use of examples
weaknesses:
- Reference data inline inflates context unnecessarily
- No table of contents for the long reference section
suggestions:
- Move the API reference to references/api.md
- Add a TOC comment at the top of the reference file
Be specific. Quote from the skill. Point to exact lines or sections. Generic observations like "could be better organized" aren't actionable.
Phase 3: Alternative Analysis
This phase asks a question most skill authors skip: is a skill even the right solution?
Evaluate these dimensions:
- Existing coverage: Does another skill already handle this? Could an existing skill be extended instead of creating a new one?
- Built-in sufficiency: Can standard Copilot tools (read_file, grep_search, run_in_terminal) handle this without a skill? If so, a skill adds overhead without proportional value.
- Design alternatives: Could the same goal be achieved with a different skill architecture? (e.g., a single skill vs. composition of smaller skills, scripts vs. inline instructions, reference files vs. embedded knowledge)
- Simplification potential: Is the skill over-engineered for what it does? Could 80% of the value be delivered with 20% of the complexity?
Produce a comparison:
alternatives_analysis:
current_approach:
description: "Dedicated skill with 3 scripts and reference files"
pros: ["Complete automation", "Handles edge cases", "Consistent output"]
cons: ["Complex setup", "Heavy context load", "Maintenance burden"]
usefulness_score: "B"
alternative_1:
description: "Extend existing skill X with a new mode"
pros: ["Less duplication", "Shared maintenance", "User already knows skill X"]
cons: ["Might bloat skill X", "Different enough to warrant separation"]
usefulness_score: "B"
alternative_2:
description: "Lightweight skill — instructions only, no scripts"
pros: ["Simple", "Easy to maintain", "Fast to load"]
cons: ["Less consistent output", "User must do more manual work"]
usefulness_score: "C"
recommendation: |
Current approach is justified because [specific reasoning].
Consider borrowing [specific element] from alternative_2 to reduce complexity.
Phase 4: Synthesize Improvement Plan
Combine findings from the review and alternatives analysis into a concrete improvement plan. Prioritize by impact:
- Must fix — Anything graded D (blocks shipping)
- Should fix — Anything graded C (notably weakens the skill)
- Nice to fix — B-grade items with easy improvements
- Architectural changes — If alternatives analysis reveals a better design
The plan should be specific enough to execute without further clarification.
Phase 5: Update
Apply the improvement plan. Follow skill-creator patterns:
- Edit SKILL.md for instruction/structure changes
- Create/update scripts in
scripts/
- Move content to
references/ if it's too long for inline
- Update the description field if triggering needs improvement
After updating, document what changed and why in a brief changelog entry (stored in the review state — not a separate file).
Phase 6: Re-Review (Loop)
Run the full review again on the updated skill. Compare grades to the previous iteration.
Loop termination conditions (any of these stops the loop):
- All criteria graded A → Skill is production-ready. Done.
- 10 iterations completed → Diminishing returns. Present the best version.
- No score improvement for 5 consecutive iterations → Plateau reached. Each iteration might try a different angle or approach — sometimes improvement comes from an unexpected direction. Only stop after 5 failed attempts, and present the best version seen so far with an explanation of what was tried.
- User interrupts → Always respect user's desire to stop early.
Review State Tracking
Track progress across iterations so the loop has memory:
forge_state:
skill_name: "example-skill"
mode: "create"
current_iteration: 3
max_iterations: 10
iterations:
- iteration: 1
grades:
skill_structure: "C"
instruction_clarity: "B"
real_world_usefulness: "B"
alternative_analysis: "C"
implementation_quality: "D"
description_triggering: "C"
lowest_grade: "D"
changes_made: |
- Moved API reference to references/api.md
- Added error handling to main script
- Rewrote description for better triggering
- iteration: 2
grades:
skill_structure: "B"
instruction_clarity: "A"
real_world_usefulness: "A"
alternative_analysis: "B"
implementation_quality: "B"
description_triggering: "B"
lowest_grade: "B"
changes_made: |
- Simplified script by removing unused helper
- Added edge case examples to SKILL.md
- Narrowed description to avoid false triggers
best_iteration: 2
converged: false
convergence_reason: null
Working with skill-creator
Forge delegates to skill-creator for the actual creation and editing work. Think of it this way:
- skill-creator = the craftsperson who writes and tests skills
- skill-forge = the quality assurance process that makes sure the output is excellent
When Forge needs to create or update a skill, it follows skill-creator's patterns:
- Interview the user (for new skills)
- Write SKILL.md with proper frontmatter and structure
- Create test cases and run evaluations (when appropriate)
- Optimize the description for triggering
What Forge adds on top:
- Structured multi-criteria review after each iteration
- Alternative solution exploration
- Grade-based convergence logic
- Automatic loop management
For test cases and evaluations, Forge uses skill-creator's eval infrastructure (evals.json, grader agent, eval-viewer) when the user wants quantitative validation. But the core value of Forge is the qualitative review loop — not every skill needs full benchmarks to be good.
Communicating with the User
Follow the same principle as skill-creator: adapt to the user's technical level. Some additional guidelines for Forge:
- Show the review summary after each iteration — the grade table is the most important thing for the user to see. Keep it scannable.
- Explain your reasoning when you grade something below A. The user should understand what you're seeing and why it matters.
- Present alternatives fairly — don't dismiss them to justify the current approach. If an alternative is genuinely better, say so and pivot.
- Report progress between iterations: "Iteration 3 done — 4 criteria at A, 2 at B. Focusing on implementation quality and description triggering next."
- Vietnamese by default for this workspace (as per copilot-instructions.md). Review artifacts and SKILL.md internals stay in English.
Quick Reference
| Situation | What Forge Does |
|---|
| "Tạo skill mới cho X" | Create via skill-creator → auto-review loop |
| "Review skill Y" | Load existing → auto-review → improve loop |
| "Nâng cấp skill Z" | Load → review → update → review loop |
| User says "đủ rồi" / "good enough" | Stop loop, present final state |
| All grades reach A | Auto-stop, present final skill |
| 10 iterations, no improvement | Auto-stop, explain plateau |
Example Flow
User: "Tạo skill mới để tự động tạo changelog từ git log"
Forge:
1. Interview → understand: auto-generate CHANGELOG.md from git commits
2. Create draft SKILL.md (via skill-creator patterns)
3. AUTO-REVIEW iteration 1:
┌───────────────────────────┬───────┐
│ Criterion │ Grade │
├───────────────────────────┼───────┤
│ Skill Structure │ B │
│ Instruction Clarity │ B │
│ Real-World Usefulness │ A │
│ Alternative Analysis │ C │ ← hasn't explored git-cliff, etc.
│ Implementation Quality │ C │ ← no script for parsing
│ Description & Triggering │ B │
└───────────────────────────┴───────┘
Lowest: C → needs improvement
4. Improvement plan:
- Research git-cliff, auto-changelog, conventional-changelog
- Compare to current "parse git log manually" approach
- Add a bundled script for commit parsing
- Tighten description
5. UPDATE skill
6. RE-REVIEW iteration 2:
┌───────────────────────────┬───────┐
│ Criterion │ Grade │
├───────────────────────────┼───────┤
│ Skill Structure │ A │
│ Instruction Clarity │ A │
│ Real-World Usefulness │ A │
│ Alternative Analysis │ A │ ← compared 3 approaches
│ Implementation Quality │ B │ ← script works, minor edge case
│ Description & Triggering │ A │
└───────────────────────────┴───────┘
Lowest: B → one more round
7. Fix edge case in script → RE-REVIEW iteration 3 → All A → Done!
8. Present final skill to user with full review history.
