Imported from celloagentclub/skill-forge (SKILL.md). Install upstream with npx skills add celloagentclub/skill-forge. Copyright stays with the author.

Skill Forge

Forge a custom skill by discovering, semantically matching, and fusing existing skills from multiple sources (GitHub, SkillsMP, SkillHub, buildwithclaude) into one skill tailored to the user's exact need.

When to Use

Invoke when the user wants any of:

• "I want a skill that does X" — and no single existing skill fits
• "Combine these skills" / "merge A and B" / "find skills for Y and integrate them"
• "Is there a skill for Z?" — when the goal is to produce a new skill, not just list candidates
• A capability gap where the user describes a need in natural language and wants a ready-to-use skill built

Do NOT use when the user only wants to browse or install an existing skill as-is — point them to skill-installer for that. Skill Forge's job is to create a new, fused skill, not to be a search index.

HARD-GATE

Do NOT search, fetch, or generate any skill content until you have produced a validated requirement spec (Phase 0) that the user has explicitly approved. This applies to every request regardless of how simple it looks. Skipping clarification is the #1 cause of forged skills that miss the mark.

The only exception: if the user has already given a precise, complete spec (rare), you may state "Your spec looks complete" and ask one confirmation question before proceeding to Phase 1.

Sources

Skill Forge searches five sources in parallel. The first is the strongest — always run it.

Prefer skills.sh install counts over SkillsMP popularity numbers when both report the same skill — skills.sh counts are real installs, SkillsMP's metric is opaque.

Details and fallbacks: read references/source-adapters.md.

Workflow

Six phases. Each phase has an explicit exit criterion — do not advance until it's met.

Phase 0 — Clarify the Need (HARD-GATE)

Read references/clarification-playbook.md in full before this phase. Summary:

1. Restate the user's request as a "How Might We" problem statement.
2. Diagnose gaps across 7 dimensions: Who-uses / Trigger-scenario / Inputs / Outputs / Constraints / Stop-conditions / Skill-vs-Agent boundary.
3. Ask in rounds using the AskUserQuestion tool. 2-4 questions per round, multiple-choice preferred, dynamic count based on remaining gaps. Branch on triggers (see playbook).
4. Stop when the user says "够了" / "先这样" / "proceed", or when all 7 dimensions are filled.
5. Produce a requirement spec one-pager (template in playbook) and get explicit user approval before Phase 1.

If the user's request is already precise and complete, say so and ask a single confirmation question instead of forcing questions. Do not manufacture ambiguity.

Exit criterion: user-approved requirement spec in context.

Phase 1 — Multi-source Recall (Parallel)

Run all source adapters that are available. Each adapter prints a JSON array of candidates to stdout; you collect and merge them.

python3 scripts/fetch_skills_sh.py --query "<keywords>" --limit 15 --json     # PRIMARY — always run
python3 scripts/fetch_skillsmp.py --query "<keywords>" --limit 15 --json
python3 scripts/fetch_github.py --query "<keywords>" --limit 15 --json
python3 scripts/fetch_skillhub.py --query "<keywords>" --limit 15 --json      # may auto-degrade
python3 scripts/fetch_buildwithclaude.py --query "<keywords>" --limit 15 --json

Run these as parallel tool calls when possible — they are independent. A source that fails or times out is skipped; it does not block the others.

Each candidate object: {name, source, url, github_ref, description, stars, full_text}. full_text may be null initially — it is lazily loaded in Phase 2 only for candidates that survive the first ranking pass. This keeps cost down when a source returns 50+ hits.

Exit criterion: merged, de-duplicated candidate pool (key by github_ref, then by name+source).

Phase 2 — Semantic Re-rank (LLM)

This is the "semantic" part. Do not fall back to keyword overlap.

1. Deduplicate by github_ref (same skill listed on SkillsMP + SkillHub + GitHub = one candidate, merge metadata).
2. First pass — cheap rank on metadata: score each candidate 0-5 on intent-match and scope-fit using only name + description against the requirement spec. Keep top 8-12.
3. Lazy-load full text for the top candidates: run scripts/common.py --fetch-full <candidate_json> (or call the source adapter's fetch-full mode) to pull SKILL.md. This calls raw.githubusercontent.com for GitHub-backed candidates.
4. Second pass — deep rank with full text: re-score the top candidates on 5 dimensions (0-5 each):
   • Intent match — does the skill's core capability address the requirement's core need? (semantic, not lexical)
   • Scope fit — is what the skill does inside the requirement's scope? Penalize tangential capability bloat.
   • Quality signals — stars, doc completeness, presence of scripts/, recency.
   • Complementarity — does adding this skill cover ground the other picks don't? Penalize redundancy with already-selected picks.
   • Fuse-ability — license friendliness, few external deps, clean structure that will integrate cleanly.
5. Present a ranked shortlist (top 5-8) with per-dimension scores and a one-line "why" per pick. Use AskUserQuestion (multi-select) to let the user confirm the final set to fuse.

Scoring guidance: read references/integration-patterns.md (the scoring rubric section). Apply it, don't improvise.

Exit criterion: user-confirmed final set of skills to fuse (1-N).

Phase 3 — Integrate (auto-select output mode)

Read references/integration-patterns.md in full. Decision tree:

• Selected skills ≤ 2 AND requirement is single-responsibility → Orchestration mode: the new skill is a thin dispatcher that invokes the selected skills in sequence. Lightest weight, no content duplication.
• Selected skills ≥ 3 OR requirement needs a custom capability → Fusion mode: decompose each selected SKILL.md, select relevant sections, reconcile conflicts, fill gaps the requirement demands but no source covers, and produce one fused SKILL.md.

Fusion algorithm (detailed in integration-patterns.md):

1. Extract each skill's skeleton (Overview / When-to-use / Workflow / Rules / References / Scripts).
2. Filter sections by relevance to the requirement spec — drop off-scope capability.
3. Reconcile conflicts (naming, step ordering, rule contradictions) by requirement priority + source quality.
4. Mark gaps (requirement needs X, no source has X) and fill them with LLM-generated content, clearly labeled [FORGED — no source covered this] so provenance stays honest.
5. Emit one unified frontmatter (strict Codex spec: only name/description/license/allowed-tools/metadata), unified references list, merged scripts where needed.

Exit criterion: draft of the new skill (SKILL.md + any references/scripts) ready in a staging location.

Phase 4 — Emit and Validate

1. Determine target path: default $CODEX_HOME/skills/<new-skill-name>/ (resolve $CODEX_HOME, fallback ~/.codex/skills). Ask the user to confirm or override the name.
2. Write the new skill files. If fusion copied scripts, also copy or rewrite them with attribution.
3. Run validation with the skill-creator validator (a standard Codex skill, usually at $CODEX_HOME/skills/skill-creator/scripts/quick_validate.py — resolve $CODEX_HOME with fallback ~/.codex):

   python3 "$CODEX_HOME/skills/skill-creator/scripts/quick_validate.py" <new-skill-dir>

   If skill-creator isn't installed, install it (skill-installer from openai/skills) or fall back to manual frontmatter checks: only name/description/license/allowed-tools/metadata fields, name is hyphen-case, description ≤ 1024 chars and no angle brackets. Fix any issues found.
4. Write a provenance file <new-skill-dir>/_provenance.md: for each section of the new skill, list which source skill it came from, that skill's URL, and its license. Preserve original license texts (MIT/Apache require this). This is non-optional for license compliance.
5. Inject continuous evolution (see Phase 5) — every skill-forge skill ships with self-improvement wired in.

Exit criterion: validated skill directory + provenance file + evolution injected.

Phase 5 — Inject Continuous Evolution

Every skill-forge-generated skill must be able to improve itself through use. Read references/evolution-protocol.md for the full protocol. The injection has two parts:

Part A — Create the feedback log. Create <new-skill-dir>/_feedback.md (empty shell with header). This file collects interaction signals over time. The shared engine scripts/evolve_feedback.py manages it.

Part B — Append the "持续进化" section to SKILL.md. At the end of the new skill's SKILL.md (after Verification / Red Flags), append the standardized evolution section from evolution-protocol.md, substituting <skill-dir> with the actual path. This section tells the generated skill:

• How to recognize the 5 signal types (correction / unclear / missing / verification / friction) during interaction
• To call evolve_feedback.py record after each interaction where a signal occurred
• To call evolve_feedback.py status and, when the threshold (5 signals) is hit, prompt the user "已收集 N 条改进信号，要不要优化我？"
• That evolution is never automatic — it always asks the user first
• How the user can manually trigger evolution or clear feedback

After injection, re-run quick_validate to confirm the appended section didn't break frontmatter (it only touches the body, so it should pass — but verify).

Then tell the user plainly:

The forged skill is at <path>. It self-improves: as you use it, it collects feedback signals, and after 5 signals it'll ask whether to optimize itself (via skill-evolver). You stay in control — nothing changes without your OK.

This mirrors the broader ecosystem: skill-forge creates, the generated skill collects feedback, skill-evolver applies improvements. Three distinct roles, no overlap.

Communication

• Show your work at each phase boundary: brief status (what was found, how many candidates, top scores) before moving on. The user should never wonder "what's happening".
• Cite sources: when presenting candidates, always show name (source) and a link. When presenting the forged skill, the provenance file is the detailed record.
• Be honest about degradation: if SkillHub 429'd, say "SkillHub was rate-limited, searched the other 3 sources". Do not silently drop a source.
• One question at a time when drilling during Phase 0; batch 2-4 broader questions in a single AskUserQuestion call when they're independent.

Non-negotiables

• Never generate skill content before the requirement spec is user-approved (HARD-GATE).
• Never present a fused section as if it came from a source when it was LLM-generated — use the [FORGED] label.
• Never drop the provenance file — license compliance depends on it.
• Never silently skip a failed source without telling the user.
• Never install the forged skill into the user's skills dir without confirming the name and path.
• Never ship a generated skill without injecting continuous evolution (Phase 5) — every skill-forge skill must self-improve.
• Never let evolution run without user consent — feedback collection is silent, but the optimization itself always asks first.

Verification

Before declaring done:

• Requirement spec was user-approved before search began
• At least 2 sources were attempted (1 may have degraded)
• Final candidate set was user-confirmed
• New skill passes quick_validate.py
• _provenance.md exists and covers every section
• _feedback.md exists (evolution feedback log shell)
• SKILL.md contains the "持续进化" section (evolution injected)
• quick_validate re-run passes after evolution injection
• User knows the install path and that the skill self-improves