workflow-forge

workflow-forge

A skill's own numbered steps ARE its procedure -- there is no separate state file to keep in sync. Improving a skill means editing that skill's SKILL.md/scripts directly, confirmed by a real run, committed to git. Git history is the whole memory: git log <path> is the lessons file, git diff/git revert is the checkpoint/rollback.

Hard Rules

1. Never edit a skill without running it first, this pass. An edit made from reading prose alone, unconfirmed by a real dispatch, is a guess.
2. Never dispatch a run inline in your own context. Subagents inherit nothing -- use the Agent tool with a fully self-contained prompt (see Run and critique).
3. Never grade a run confirmatory, and never defer a real finding. A second, fresh-context Agent actively hunts for fault. The moment a finding is evidence-backed (cited, re-checked, not asserted), edit the file it's in -- immediately, same pass, whether that's the target skill's own SKILL.md or a sibling file in its host project.
4. Never invent history. The record of what changed and why is the git commit for that change, written when it's made -- not a separate log kept in sync by hand.
5. Never remove a skill's capability from one run's evidence. One run adds a step/case a skill didn't handle; a failure recurring across 2+ independent runs justifies removing or replacing something.
6. Never leave a deterministic step as re-derived prose. If a run shows a step always produces the same output from the same input, write it as a script beside the skill's SKILL.md and have that step call it.
7. Never treat "found" as "fixed." A finding noted only in a critique response with no corresponding file edit is observed, not improved -- edit the file, read it back to confirm, commit.

Improving an existing skill (including yourself)

Point this at any skills/<name>/SKILL.md. Read it. Its numbered steps (or lack of them) are the current procedure -- there is nothing else to load.

1. Run and critique -- isolated subagent, every time

1. Dispatch via the Agent tool, self-contained prompt: absolute path to the target's SKILL.md, a real concrete task it should plausibly handle (built from its own description if none is given), and an explicit instruction to actually run the procedure and report exactly what happened -- no simulation.

2. Dispatch a second, fresh-context Agent, first run's full report embedded verbatim in its prompt (not a file pointer -- inheritance is zero per Hard Rule 2, so anything the critic checks against must be pasted in). Paste this brief verbatim, filled in:

   Only job: find fault with this run's result and process. Report one finding per category below, even if a category is empty -- do not skip a category just because nothing jumps out.

   1. By-design flagged as broken -- correct behavior misread as a bug.
   2. Mis-attributed evidence -- a claim that doesn't match what your own independent re-check of the same file/command shows.
   3. Unverified claim -- "it worked" with nothing cited to back it.
   4. A real bug in the host project, not just the skill's own prose -- a sibling script it called, a config file, anything the run touched. Re-check the target file/command yourself; do not trust the first run's paraphrase of it. [FIRST RUN'S FULL REPORT, VERBATIM, PASTED BELOW]

2. Land every evidence-backed finding, same pass

The moment a finding is confirmed (re-checked, not asserted): Edit the file it's actually in -- the target's SKILL.md, a script beside it, or a project file -- and Read it back to confirm the write landed. Do this for every confirmed finding before moving on; nothing waits for a "next iteration."

A step proven deterministic (same input, same output, across the runs so far) becomes a script next to the skill's SKILL.md, invoked from that step instead of re-described in prose (Hard Rule 6).

3. Commit, then run once more to confirm

git add the changed files and commit with a message stating what changed and the evidence for it -- this commit is the only record that needs to exist. Then repeat step 1 against the now-edited skill. If the finding that motivated the edit is gone and nothing new and worse appeared, stop -- the fix held. If it regressed, git revert the commit and try a different fix.

Repeat 1-3 until a full run finds nothing further to land -- that's the stopping point, not a fixed number of passes. If whoever invoked this skill scoped it to one bounded, reportable pass, that explicit scope wins over this default -- report the single pass's result and stop; do not silently loop past a caller-stated bound.

Building a new skill

A skill is one file: skills/<name>/SKILL.md with name/description frontmatter and numbered steps. Write it directly for the real task at hand, then run it through steps 1-3 above like any other target -- a skill drafted from a guess and never run is unverified by construction.

Gotchas

• A skill written earlier in the same turn is not Skill-dispatchable mid-turn -- the skill list loads at session start. Use the Agent tool to follow its SKILL.md directly; this is the normal path here, not a fallback.
• Only workflow-forge (via steps 1-3) edits a target's SKILL.md. A target run standalone, outside this loop, just executes its current instructions -- there's no marker to check, because there's nothing conditional to write.