skill-forge

Skill Forge

Version 0.4.1. Adds an opt-in recovery runner for the verified macOS SwiftBridging compiler conflict that blocked REA JavaScript analysis. The core skill-building workflows and bundled Anatomy renderer remain available. See the recovery guide, validation report and integration scope.

Turn a useful idea into a reusable AI skill—and improve it with evidence.

Describe a workflow in ordinary language, or say “Based on this conversation, build me a skill.” Skill Forge extracts what is settled, asks and challenges what matters, shows an implementation spec and verification plan, then builds and checks an installable skill. It also improves existing skills and evaluates improvements to its own interview and tools.

• Simple, clear ideas can go straight to a draft. Complex uncertainty gets deeper questions.
• Refine through focused questions, examples and constructive challenge until material gaps close. Say quick, thorough, expert challenge, draft now, skip, or resume to control the pace.
• Choose how to receive the skill itself: local Markdown, an installable folder/ZIP, a GitHub repository, or another destination. Settled choices are remembered.
• Before implementation, Skill Finder delegates a bounded search for useful foundations, inspecting actual source, licenses and fit. It has honest fallbacks when browsing or subagents are unavailable.
• Learn from complete source files using ordinary file tools; use the optional REA adapter for shipped-artifact or runtime-dependent questions. Missing providers leave explicit evidence gaps.
• Automatically include the real Anatomy renderer and notices when the generated skill needs an explanatory physical mechanism. Text/CSV-only work, ordinary flowcharts and explicit opt-outs skip it.
• See what will be built and how it will be checked before implementation. Say review first to pause for edits; the pause is optional, so draft now and already-authorized work can continue after the plan.
• Available useful subagents automatically help construct resources, review the result or run independent checks. Small tasks can stay in one context; unavailable tools are disclosed.
• Successful updates are applied automatically after predefined checks, with history and rollback. Failed or untested candidates stay separate.
• Private preferences and conversations stay outside published source by default.

Install and start using Skill Forge

You need access to Codex, Claude Code, or another capable chat model. Skill Forge itself needs no paid API or custom service. Python is optional: only the validation, resource-attachment, packaging and managed-update helpers require Python 3.9 or newer. Node.js 20.10+ is optional and used only when building the bundled Anatomy example; a modern browser is needed to view and verify the interactive output. REA is a separate optional tool with its own runtime/provider requirements. Installing Forge does not install Node, REA or a browser.

Choose the skill ZIP for Codex/Claude Code, or the portable ZIP for another capable chat model. Keep the full skill folder when executable resources are needed.

Codex or Claude Code: install without commands

1. Download skill-forge-v0.4.1.zip and extract it.
2. Copy the complete skill-forge folder, including its references, scripts, templates, resources and nested adapters, to one destination below. Create missing parent folders. Copying only SKILL.md is incomplete.
3. Open a new session in your host and invoke Skill Forge as shown below. If it does not appear, restart the host.

~ and %USERPROFILE% mean your home folder; replace <project> with your project's folder. On Windows you can paste %USERPROFILE% into File Explorer's address bar; native backslashes also work. Personal means your local user installation; project means only the selected repository. Avoid installing the same named skill at multiple scopes.

In Codex, select Skill Forge or type:

$skill-forge Create a skill that turns rough meeting notes into action items.
Keep unknown owners and dates explicit. Use your judgment. Draft now.

In Claude Code, type the same request starting with /skill-forge instead of $skill-forge.

The Codex guide and Claude Code guide also include optional managed installation commands for macOS/Linux and Windows PowerShell, updating, removal and troubleshooting. For a manual update, back up and compare your existing folder before replacing it. Managed updates refuse customized copies rather than overwrite them.

Other capable LLMs: use the portable prompt

1. Download skill-forge-portable-v0.4.1.zip and extract it.
2. Upload skill-forge-prompt.md, or paste its complete contents into a new conversation. Use the full bundle, not just the short installed SKILL.md. Choose a model with enough context for the entire file.
3. Say: “Use Skill Forge to build a skill for [my repeated workflow].” Supply relevant context and references. With no file tools, it returns complete file contents for you to save.

No installation, Python or operating-system-specific command is needed for this route. Without browsing, subagents or execution, those parts remain unavailable and must be reported honestly. See the plain-chat guide.

The instructions work as text across operating systems. Installation guides include Windows PowerShell and macOS/Linux commands plus manual whole-folder copying without Python. Intel/x64 and ARM are processor architectures; choose a host/Python version available for your machine. See compatibility for actual tested OS/CPU combinations and the difference between helper tests and native model execution. Local installation does not install the skill on every device or cloud chat account.

Download the latest release: the skill ZIP contains an installable skill-forge/ folder; the portable ZIP contains the standalone prompt and license; the source ZIP contains examples, tests and documentation. See compatibility for what was actually tested.

What you receive on first use

After installation, try:

Use Skill Forge to build a skill that turns my meeting notes into action items. Keep unknown owners and dates explicit. Return a Markdown table. Draft now.

Codex users can explicitly start with $skill-forge; Claude Code users with /skill-forge. Plain-chat users first supply the portable prompt. Your generated skill will include its own SKILL.md, any needed supporting files, sample requests, installation steps and a short validation report. It does not need Skill Forge to run.

For a plan you want to edit first:

Based on this conversation, build me a reusable skill. Preserve my final corrections and use synthetic examples. Show the implementation spec and how you will verify it. Review first; wait before building.

For a project, supply the relevant files or accessible authorized project context. Skill Forge states what it actually read; it cannot see hidden chats or an entire project merely because you name one. See conversation/project intake and other LLMs.

Review behavior: the plan and concrete checks appear before the artifact. They can be followed by implementation in the same response. Say “review first; wait before building” if you want a separate turn to edit the plan.

For the first result, check one realistic input and a failure case. Tell the builder what was wrong or changed:

Improve this skill: it assigns a speaker as the owner even when nobody accepted the task. Keep its table format and meeting order.

Or improve the builder:

Evaluate a Skill Forge improvement: users who ask for a spreadsheet are not finding the output-destination question. Compare retrieval before and after, preserve the prior version, and adopt only if checks pass.

Remaining limitations and what was actually tested

The v0.4.0 model comparison passed all six candidate scenarios, including two held-out cases. Local helper checks recorded42 passes and1 Windows-only skip. The maintainer reported the required HTML layout, native keyboard and reduced-motion checks working; independent review accepted that manual evidence. Browser/version remains unknown and automated browser coverage is not claimed. Historical model/host results below apply to their named earlier versions; they are not a pass for the new behavior cases.

Skill Forge implements the requested workflow; it does not guarantee perfect skills or identical behavior on every model. Read these boundaries before relying on it:

The earlier v0.3.0 release also passed actual rollback/customization checks and clean first-use checks from downloaded public packages. See the validation report, compatibility record, requirements map and release verification receipt for evidence and qualifications.

You can combine Skill Forge with Codex's built-in skill creator for authoring or review. Forge does not silently modify the vendor-managed creator; see how they work together.

What happens during a session

The builder maintains a compact brief of confirmed needs, proposed defaults, assumptions, examples, acceptance checks, open questions, skill delivery, source coverage and research status. It inspects available facts before asking you. Each answer or example can reveal the next dependent question. A coverage pass checks consequential gaps and weak assumptions without a fixed questionnaire. The skill’s own delivery choice is separate from the document, spreadsheet or other output it will later produce. Repairs preserve an existing skill’s delivery context unless you ask to change it. Without file access, the builder returns complete prior and replacement contents for you to save; unavailable execution prevents adoption, not drafting the repair.

Once the brief is ready, Skill Finder sends a researcher a sanitized task. It searches GitHub, Hugging Face when relevant, and other primary resources; checks actual files, revision and reuse rights; and recommends a foundation or original implementation. Findings can reopen a specific design decision. Research is bounded, can be declined, and does not authorize installing fetched code or publishing your materials.

Before building, it presents an implementation spec: intended behavior, files/dependencies, assumptions, work and delegated roles, delivery/privacy, concrete acceptance inputs, expected outcomes, failure conditions and unavailable checks. Review pauses are optional: review first or spec only waits for you; otherwise authorized work proceeds. Draft now shows a compact plan and draft in the same response. If delivery is undecided, it returns provisional saveable text and leaves that choice for finalization without appending another required question. User edits update the spec and affected checks before building. Supplied acceptance examples keep their exact inputs and expected results; supporting resources receive their own checks against the final behavior.

For useful separable work it automatically launches available constructors, resource authors, reviewers or evaluators with bounded tasks and clear file ownership. It waits for results and integrates them; a promise that a subagent or test ran is not evidence. Tools, permissions and model capability still determine what can actually execute.

When a session pauses, save its private record or copy its handoff into the next chat. Improvement means revised files and recorded evidence; it does not retrain a model or promise memory across unrelated conversations.

Worked examples cover research and writing, an adaptive prompt builder, a planner handling an exam, and a correction to an existing skill. The public inputs are fictional. Authored demonstrations are labeled separately from executed evaluation results: v0.1.0, v0.2.0, and v0.3.0.

Optional REA and Anatomy resources

The integration guide explains source versus shipped-artifact evidence, automatic selection for physical explainers, the exact bundled file slice, optional dependencies and helper commands. Generated skills receive their own resources and work without Forge. An adapter is workflow guidance; it is not proof that a tool is connected or that an analysis, render or browser check ran.

Claude metadata checks in v0.3.1

The Claude guide review identified a narrow helper gap. Optional compatibility values are now checked for 1–500 characters; omit the field when no environment requirements apply. For Claude-targeted skills, use the opt-in profile from a source checkout:

python3 skills/skill-forge/scripts/forge.py validate /path/to/my-skill --profile claude

On Windows use py -3 instead of python3. The profile checks reserved names and discovery-description angle brackets; body XML/HTML is allowed. Generic validation remains the default. This checks a supported metadata subset, not full YAML validity, native Claude upload success or model quality.

Evidence and automatic updates

A candidate connects an observation to a hypothesis, patch and checks declared before testing. It must preserve existing acceptance criteria, pass relevant regressions and demonstrate its intended benefit against the prior version. Broader builder changes need held-out scenarios. Formatting alone cannot establish behavioral improvement.

The optional Python helper snapshots files, freezes the evaluator and criteria, checks hash-bound evidence, adopts passing candidates, and rolls back safely. It does not generate or authenticate model results. Use genuine execution artifacts and a trusted evaluator. Default improvement runs allow three candidates and a 30-minute wall-clock limit; failures or missing evidence preserve the active version. Helper commands and evidence format.

For local development with Python 3.9 or newer:

python3 skills/skill-forge/scripts/forge.py validate skills/skill-forge
python3 -m unittest discover -s tests -v
python3 skills/skill-forge/scripts/forge.py bundle --skill skills/skill-forge --output portable/skill-forge-prompt.md --check

On Windows, use py or python in place of python3; the installation guides include complete PowerShell examples. Before installing a generated skill, verify that its innermost folder matches the name in its metadata. Preserve versions under separate parents (baseline/skill-name, candidate/skill-name). See the release report for exact results, earlier failure rechecks and remaining limits.

The canonical builder lives in skills/skill-forge/. The portable prompt is generated from it, so edits cannot quietly drift. Its text-only form does not embed the Anatomy renderer files; an explanatory visual target needs the complete folder assets or an honest pending asset-copy step. See plain-chat limits. Managed installations refuse to overwrite customized copies; keep personal settings outside the shared skill.

Contribute an improvement

Report a failure or propose a question. A helpful contribution includes a realistic input, expected behavior, actual failure, and why the proposed change helps. Search the question library first: fewer useful questions beat more repetitive questions. Accepted changes gain a regression case and a versioned change record. Do not submit private transcripts or credentials.

See foundations and comparison, source ledger, notices, and changelog. Original project material is MIT licensed. Installation, tool access and results vary by host; external publication always requires authorization for that destination.

The v0.3.0 checks passed all 21 original scenarios (84 required conditions), all 15 supplemental interview items, and the navigation/package checks. A fresh Codex CLI 0.164.0 invocation discovered the installed skill and returned a standalone draft. Historical baseline/model limits and untested native hosts are documented in the validation report.

Track requested capabilities in REQUIREMENTS.md, current work in HANDOFF.md, and the project usage policy in MAINTENANCE.md.

REA JavaScript compiler recovery on macOS

If REA reports redefinition of module 'SwiftBridging', use the guarded macOS recovery guide. The opt-in Python runner checks the actual diagnostic and matching module definitions, then supplies a temporary compiler overlay only to the requested command. It does not edit Apple files, disable REA ownership checks, install REA or repair every Swift failure. Existing custom compiler/SDK selections are refused. Normal host process inspection is still required; a sandbox may deny it. Failed or interrupted runs retain temporary state when native descendant cleanup is uncertain.

The executable runner is included in the full skill/source ZIP, not the portable text bundle. Other operating systems keep their ordinary REA setup; this specific workaround refuses non-macOS systems. See v0.4.1 evidence and limits.