Skip to content
Back to search

skillforge

"Use when creating, improving, finding, or auditing agent skills - the user says 'create a skill', 'do I have a skill for X', 'improve the X skill', 'which skill should I use', asks whether a skill exists for a task, or wants to validate, test, evaluate, package, or health-check skills. Also use for skill ecosystem maintenance (duplicate detection, stale skills, trigger collisions) and advisor checkpoints."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tripleyak-skillforge/badge.svg)](/listings/tripleyak-skillforge)

HTML

<a href="/listings/tripleyak-skillforge"><img src="/api/listings/tripleyak-skillforge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/tripleyak/SkillForge.git /tmp/skillforge
cp -r /tmp/skillforge ~/.claude/skills/skillforge
cd ~/.claude/skills/skillforge && rm -rf README.md LICENSE CONTEXT.md docs .git .gitignore .skillignore index.html assets/images scripts/tests SKILLFORGE_AUDIT.md
cp /tmp/skillforge/commands/skillforge.md ~/.claude/commands/skillforge.md   # optional /skillforge command

Optional advisor + hooks (interactive, everything opt-in):

python3 ~/.claude/skills/skillforge/scripts/install_skillforge.py

Requirements: Claude Code (or Codex CLI), Python 3.8+ (stdlib only; PyYAML used if present).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 127 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: skillforge
  3. description: "Use when creating, improving, finding, or auditing agent skills - the user says 'create a skill', 'do I have a skill for X', 'improve the X skill', 'which skill should I use', asks whether a skill exists for a task, or wants to validate, test, evaluate, package, or health-check skills. Also use for skill ecosystem maintenance (duplicate detection, stale skills, trigger collisions) and advisor checkpoints."
  4. license: MIT
  5. user-invocable: true
  6. allowed-tools:
  7. - Read
  8. - Glob
  9. - Grep
  10. - Bash
  11. - Write
  12. - Edit
  13. - Task
  14. metadata:
  15. version: 6.0.0
  16. domains: [meta-skill, skill-creation, skill-testing, orchestration, routing]
  17. type: orchestrator
  18. ---
  19. # SkillForge 6 - Skill Router, Creator & Ecosystem Maintainer
  20. Routes any skill-related request to the right action (use, improve, create, compose), creates new skills through an evidence-driven pipeline, and maintains the health of the whole skill ecosystem. Core principle: **skill quality is a property of behavior, not documents - a skill is done when a fresh agent demonstrably does better with it than without it.**
  21. ## Routing (Phase 0)
  22. Always triage before creating anything:
  23. ```bash
  24. python3 scripts/discover_skills.py # refresh index (auto-refreshes if >24h old)
  25. python3 scripts/triage_skill_request.py "<the user's request>" --json
  26. ```
  27. | Triage result | Action |
  28. |---|---|
  29. | Strong match (existing skill) | Recommend it; do not create a duplicate |
  30. | Moderate match | Offer IMPROVE_EXISTING on the matched skill |
  31. | Weak/no match + create intent | Proceed to creation pipeline |
  32. | Multi-domain | Suggest composing existing skills |
  33. | Ambiguous | Ask one clarifying question |
  34. Match bands are keyword-evidence heuristics, not calibrated probabilities - report them as "strong/moderate/weak match", never as percent confidence.
  35. ## Creation pipeline
  36. Run phases in order. Each phase's detailed procedure lives in its reference - read the reference when you reach the phase, not before.
  37. **0. Baseline gate (RED).** Before designing anything, dispatch a fresh subagent (Task tool) on 1-2 representative target tasks WITHOUT the skill. Capture verbatim what it does wrong. **If the baseline does not fail, stop - the skill is unnecessary.** The failures become the skill's test cases and its description keywords. See [references/testing-and-evals.md](references/testing-and-evals.md).
  38. **1. Analysis.** Identify explicit, implicit, and discovered requirements. Apply the three load-bearing lenses - Inversion (what guarantees failure → anti-patterns), Pareto (which 20% of scope delivers 80% → cut the rest), Root Cause (is this the real problem?) - plus any others from [references/multi-lens-framework.md](references/multi-lens-framework.md) that earn their tokens. Classify the failure type you are guarding against and match the guidance form to it (see the failure-form table in [references/testing-and-evals.md](references/testing-and-evals.md)). Choose instruction specificity with [references/degrees-of-freedom.md](references/degrees-of-freedom.md). Decide scripts with [references/script-integration-framework.md](references/script-integration-framework.md).
  39. **2. Specification.** Write the spec using [references/specification-template.md](references/specification-template.md). Minimal tier (problem, requirements, decisions with WHY, success criteria, test scenarios) for most skills; full tier (temporal projection, obsolescence triggers, extension points) only for infrastructure skills. Never fill a section you cannot ground - omit it.
  40. **3. Generation in fresh context.** Dispatch a subagent (Task tool) that receives ONLY the spec and the baseline failures - not the analysis transcript - to write SKILL.md and supporting files. Scaffold first: `python3 scripts/init_skill.py <name> --path <skills-dir>`. Description doctrine: trigger conditions only, third person, symptom keywords, never a workflow summary. Budget: SKILL.md under 1,500 words; move depth to references/; `<details>` tags save zero tokens for agents - do not use them.
  41. **4. Execution testing (GREEN).** Re-run the baseline tasks WITH the skill via fresh subagents. Gate on behavioral delta: the with-skill runs must not exhibit the baseline failures. Then run the description-triggering check (positive and near-miss queries). Iterate description and body against observed failures, not hunches. For improvements to existing skills, use blind A/B judging. Full protocols: [references/testing-and-evals.md](references/testing-and-evals.md).
  42. **5. Review = lint + one adversarial reviewer.** Mechanical gates first:
  43. ```bash
  44. python3 scripts/validate_skill.py <skill-dir> # structure, frontmatter, lint (pinned models, word budget, description shape)
  45. python3 scripts/check_docs_safety.py <skill-dir>
  46. ```
  47. Then one fresh-context subagent prompted to REFUTE the skill (find the case where it misleads, over-triggers, or fails its own scenarios), carrying the reviewer checklists in [references/synthesis-protocol.md](references/synthesis-protocol.md). Fix what it proves; ship what survives. Do not convene approval panels - same-model unanimity measures nothing.
  48. **6. Ship with evals.** Every generated skill keeps its tests: an `evals/` directory (trigger queries + behavioral scenarios + assertions) so future edits can be regression-tested with `python3 scripts/run_skill_evals.py <skill-dir>`. Iterate post-ship with [references/iteration-guide.md](references/iteration-guide.md).
  49. ## Frontmatter and platform facts
  50. Write frontmatter against the current Claude Code field set (17 fields) documented in [references/claude-code-frontmatter.md](references/claude-code-frontmatter.md), which also covers hooks (hooks receive JSON on stdin, not env vars), `context: fork`/`agent`, `$ARGUMENTS`, and the agentskills.io portability limits (64-char name, 1024-char description) that `validate_skill.py` enforces. Never pin dated model IDs (`claude-*-YYYYMMDD`) - the validator rejects them.
  51. ## Ecosystem maintenance
  52. ```bash
  53. python3 scripts/skillforge_doctor.py # trigger collisions, duplicates, stale refs, token budgets, description lint
  54. python3 scripts/compile_skill.py <dir> --target claude|codex|agentskills
  55. python3 scripts/package_skill.py <dir> ./dist # .skill zip, honors .skillignore
  56. python3 scripts/mine_skill_friction.py --consent # opt-in: mine local transcripts for skill friction
  57. ```
  58. Use doctor output to drive IMPROVE_EXISTING work; use friction reports as advisor evidence.
  59. ## Context Skill Advisor
  60. Proactive suggestions are delivered through Claude Code hooks (SessionStart surfaces the queue; UserPromptSubmit scores checkpoints inline) - no daemon. Configure with `python3 scripts/install_skillforge.py` (interactive; hooks and Personal Context scanning are **opt-in**, never default). Manage the queue: `python3 scripts/context_advisor.py list|use|snooze|dismiss`. Suggestions are evidence-backed and never auto-invoke a skill.
  61. ## Script inventory
  62. | Script | Purpose |
  63. |---|---|
  64. | `discover_skills.py` | Build/refresh the cross-runtime skill index |
  65. | `triage_skill_request.py` | Route input to use/improve/create/compose/clarify |
  66. | `validate_skill.py` | Full structural + lint validation (`quick_validate.py` = fast subset) |
  67. | `run_skill_evals.py` | Run a skill's evals/ regression suite |
  68. | `skillforge_doctor.py` | Ecosystem health report |
  69. | `init_skill.py` | Scaffold a new skill (with evals/) |
  70. | `compile_skill.py` | Compile a skill for a target runtime |
  71. | `package_skill.py` | Package as .skill archive |
  72. | `mine_skill_friction.py` | Opt-in transcript friction mining |
  73. | `context_advisor.py` / `install_skillforge.py` | Advisor queue and setup |
  74. | `check_docs_safety.py` | Unsafe interpolation check |
  75. Script exit codes: 0 success, 1 failure, 2 usage/consent error, 10 validation failure, 11 verification/dependency failure.
  76. Extension points: new lint checks in `validate_skill.py`; new doctor checks in `skillforge_doctor.py`; new compile targets in `compile_skill.py`; new lenses in `references/multi-lens-framework.md`.
  77. ## Anti-patterns
  78. | Avoid | Instead |
  79. |---|---|
  80. | Creating without a failing baseline | Run the RED gate; no failure = no skill |
  81. | Description that summarizes workflow | Trigger conditions only - agents act on summaries and skip the body |
  82. | Body "Triggers" sections as a mechanism | Only the frontmatter description drives invocation |
  83. | Approval panels and self-scored gates | Lint what is falsifiable; adversarially refute the rest |
  84. | `<details>` blocks for "progressive disclosure" | Separate reference files loaded on demand |
  85. | Pinned dated model IDs | Family aliases or omit `model:` |
  86. | Duplicating an existing skill | Phase 0 triage first, always |
  87. ## Verification checklist
  88. - [ ] Baseline failure captured before writing (RED)
  89. - [ ] With-skill runs clear the baseline failures (GREEN)
  90. - [ ] Trigger check passes on positive and near-miss queries
  91. - [ ] `validate_skill.py` and `check_docs_safety.py` pass
  92. - [ ] Adversarial reviewer's proven issues fixed
  93. - [ ] `evals/` shipped with the skill; `run_skill_evals.py` passes
  94. - [ ] SKILL.md under 1,500 words (`wc -w`)
README.md · README · 83 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # SkillForge v6
  2. **A skill creator that proves its skills work.**
  3. SkillForge routes any skill-related request (use, improve, create, compose), creates new skills through an evidence-driven pipeline, and maintains the health of your whole skill ecosystem. Its core principle: **skill quality is a property of behavior, not documents** - a skill is done when a fresh agent demonstrably does better with it than without it.
  4. ## What v6 changed (and why)
  5. v6 is a ground-up rework following a deep external audit (see `SKILLFORGE_AUDIT.md` on the repo, not shipped with the skill). The headline shifts:
  6. | v5 | v6 |
  7. |---|---|
  8. | 4-agent "unanimous synthesis panel" reads the skill | Skills are **executed**: baseline (RED) runs before writing, with-skill (GREEN) runs after, behavioral delta is the gate |
  9. | Self-scored "timelessness >= 7" approval | Falsifiable checks moved to lint (`validate_skill.py`); one adversarial reviewer refutes what lint can't catch |
  10. | 5,049-word SKILL.md with `<details>` "progressive disclosure" | 1,158-word SKILL.md; depth lives in `references/` loaded on demand |
  11. | Descriptions = "what this skill does" | Descriptions = trigger conditions only (workflow summaries make agents skip the body) |
  12. | launchd background advisor that analyzed `/` and queued into a file nothing read | Advisor delivered through Claude Code hooks (SessionStart + UserPromptSubmit), caps enforced, opt-in |
  13. | Personal-directory scanning on by default, hardcoded GitHub handles | Personal Context strictly opt-in with recorded consent; no shipped defaults |
  14. | Hand-rolled YAML parser that failed SkillForge's own SKILL.md | One shared typed parser (`scripts/frontmatter.py`), 100+ unit tests, and a regression test that SkillForge validates itself |
  15. | Index missed the Claude Code plugin cache entirely | Cross-runtime discovery: personal, Codex, Claude Code plugin cache; deduped; auto-refresh |
  16. ## The pipeline
  17. ```
  18. Phase 0 TRIAGE index + word-boundary matching -> USE | IMPROVE | CREATE | COMPOSE | CLARIFY
  19. Phase 0b RED GATE fresh subagent attempts the task WITHOUT the skill; no failure = no skill
  20. Phase 1 ANALYSIS load-bearing lenses (Inversion, Pareto, Root Cause), failure-form matching
  21. Phase 2 SPEC tiered (minimal default / full for infrastructure), decisions + WHY
  22. Phase 3 GENERATE fresh-context subagent receives ONLY the spec + baseline failures
  23. Phase 4 GREEN GATE with-skill runs must clear the recorded baseline failures; trigger tests
  24. Phase 5 REVIEW lint (validate_skill.py) + ONE adversarial reviewer charged to refute
  25. Phase 6 SHIP with evals/ - a per-skill regression suite runnable forever after
  26. ```
  27. ## What no other skill creator has
  28. - **Dedup before create** (Phase 0): an index of every skill across runtimes answers "should this exist?" first.
  29. - **Skills ship with their tests**: `evals/` (trigger queries + behavioral scenarios) + `run_skill_evals.py` = regression testing for skills.
  30. - **Ecosystem doctor**: `skillforge_doctor.py` finds trigger collisions between skills, duplicates, stale file references, budget violations, and pinned models across your entire roster.
  31. - **Cross-runtime compile**: author once, `compile_skill.py --target claude|codex|agentskills`.
  32. - **Friction mining** (opt-in): `mine_skill_friction.py --consent` finds skill gaps in your own local session history.
  33. - **Proactive advisor** (opt-in): evidence-backed skill suggestions delivered via hooks, never auto-invoked.
  34. ## Install (Claude Code)
  35. ```bash
  36. git clone https://github.com/tripleyak/SkillForge.git /tmp/skillforge
  37. cp -r /tmp/skillforge ~/.claude/skills/skillforge
  38. cd ~/.claude/skills/skillforge && rm -rf README.md LICENSE CONTEXT.md docs .git .gitignore .skillignore index.html assets/images scripts/tests SKILLFORGE_AUDIT.md
  39. cp /tmp/skillforge/commands/skillforge.md ~/.claude/commands/skillforge.md # optional /skillforge command
  40. ```
  41. Optional advisor + hooks (interactive, everything opt-in):
  42. ```bash
  43. python3 ~/.claude/skills/skillforge/scripts/install_skillforge.py
  44. ```
  45. Requirements: Claude Code (or Codex CLI), Python 3.8+ (stdlib only; PyYAML used if present).
  46. ## Toolbox
  47. | Command | Purpose |
  48. |---|---|
  49. | `python3 scripts/discover_skills.py` | Build/refresh the skill index |
  50. | `python3 scripts/triage_skill_request.py "<request>" --json` | Route a request |
  51. | `python3 scripts/validate_skill.py <dir>` | Full validation + lint |
  52. | `python3 scripts/run_skill_evals.py <dir> [--live]` | Run a skill's regression evals |
  53. | `python3 scripts/skillforge_doctor.py` | Ecosystem health report |
  54. | `python3 scripts/init_skill.py <name> --path <dir>` | Scaffold (includes evals/) |
  55. | `python3 scripts/compile_skill.py <dir> --target <t>` | Cross-runtime compile |
  56. | `python3 scripts/package_skill.py <dir> ./dist` | Package as .skill |
  57. | `python3 scripts/mine_skill_friction.py --consent` | Mine local transcripts for skill gaps |
  58. CI: copy `assets/templates/github-workflow-skill-ci.yml` into `.github/workflows/` of any skill repo.
  59. ## Releases
  60. Version history and detailed release notes live on the [releases page](https://github.com/tripleyak/SkillForge/releases). v6.0.0 is a ground-up rework; the audit that drove it ships in-repo as [SKILLFORGE_AUDIT.md](SKILLFORGE_AUDIT.md).
  61. ## License
  62. MIT - see [LICENSE](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.