Skill Forge

A small pipeline for turning complex AI-assisted workflows into reusable skills. It is for anyone who does multi-step work with an AI agent (design, automation, data pipelines, infrastructure) and wants the hard-won lessons from one run to make the next run faster and more correct.

The problem

The context window is volatile. A long session accumulates the exact knowledge that should become a repeatable skill: the ordering constraint you discovered, the dead end you backed out of, the convention you settled on. Then compaction or a /clear wipes it, and the next run relearns the same lessons from scratch.

The transcript is not the answer. It records keystrokes at the wrong altitude and is gone the moment context resets.

How it works

Three stages, two skills.

• Capture. While you work, the workflow-capture skill maintains an append-only, tagged journal on disk (a WORKLOG.md). It records why, not what: decisions, sequencing, corrections, dead ends, conventions, discoveries.
• Carry. The journal is a file, so context resets stop mattering. Before a compaction or /clear, you write a checkpoint. A fresh session reads the journal and continues.
• Crystallize. Afterward, the skill-forge skill reads the journal and routes each tagged entry into the right section of a new skill: ordered steps, hard rules, reference notes. Then it validates the skill against a few realistic prompts.

The result is a skill that makes the next run of that workflow cheaper and more correct, with the original journal archived alongside it for provenance.

Quickstart

New to this and not a coder? Start with AI-SETUP-PROMPT.md. It walks you through getting the repo onto your computer and pasting one prompt that has your AI assistant install everything for you.

If you are comfortable with the basics:

1. Clone this repo.
2. Copy the two skills into your agent's skill path so they load:
   • skills/workflow-capture/
   • skills/skill-forge/ (In Claude Code that is .claude/skills/ in a project or ~/.claude/skills/ globally. Prefer a symlink so edits propagate.)
3. Start a complex piece of work. The capture skill opens a worklog at _worklogs/YYYY-MM-DD-<slug>/WORKLOG.md and appends a tagged entry whenever a real lesson surfaces.
4. When the work is done, point the forge skill at the worklog: "turn this worklog into a skill." It drafts, validates, and archives.

See RUNBOOK.md for the full implementation guide, including the tag schema, the entry format, the checkpoint and resume protocol, and optional hardening.

What is in here

skill-forge/
  README.md                 you are here
  RUNBOOK.md                step-by-step implementation guide (canonical)
  AI-SETUP-PROMPT.md        paste into your agent to scaffold this in your own setup
  LICENSE                   MIT
  skills/
    workflow-capture/SKILL.md
    skill-forge/
      SKILL.md
      references/{tag-schema.md, skill-anatomy.md}
  hooks/                     optional: make the capture habit automatic
    skill_forge_session_start.py   re-injects the active worklog path each session
    install_hook.py                safe, idempotent installer for settings.json
    README.md                      hook install + configuration guide
  examples/
    WORKLOG.example.md          a realistic worklog
    figma-design.example/       a skill produced from that worklog
  _worklogs/                 your runtime worklogs land here (gitignored)

Optional: automatic reminders

The skills work on instruction alone. If your agent supports lifecycle hooks, the hooks/ directory wires up a Claude Code SessionStart hook that re-injects the active worklog path at the start of every session, including after a /clear or a compaction. That closes the gap where a context reset makes you forget the journal exists. Install with python hooks/install_hook.py; details in hooks/README.md.

License and attribution

MIT, see LICENSE. Built by Michael Frostbutter at Agenius AI Labs. If you build on it, a link back is appreciated but not required.