Skill Forge

Most skills are static instructions. They may work today, but tomorrow's agent starts from the same page. The mistakes, fixes, tool quirks, and better decisions discovered during the run disappear with the conversation.

Skill Forge creates living skills. They read what previous runs learned before they start, then record what happened, what changed, and what the next run should know.

When a lesson proves useful, it moves into the skill itself. The method becomes stronger instead of leaving another note for the agent to rediscover later.

This is the method I use to create and maintain the skills behind my own agents. I removed my workspace details and packaged the process so your agent can use it inside yours.

Every run can improve the next one

The improvement loop is simple enough to inspect.

1. Before the run: the skill reads its local setup, the useful lessons from past runs, and the recent run history.
2. After the run: it logs what happened, updates local facts that changed, and saves any lesson a future run needs.
3. When the lesson is proven: it moves into the main method or the right reference. The learnings file becomes short again, and the skill itself gets better.

Every change also records what was wrong, what changed, which files changed, and why the new version is better. That prevents one copy from improving silently while every other copy stays behind.

This loop is deliberately switched off for skills that govern policy, behavior, or writing style. Those skills change only through an explicit, reviewed edit.

Creating the first skill is easy. Keeping twenty useful is not.

You can ask an agent to write a SKILL.md and get something that looks convincing. The problems appear later.

Two skills start answering the same request. Triggers become vague. Local paths leak into instructions that should be portable. A fix stays buried in one conversation. A scheduled job keeps running after nobody remembers which file controls it.

Skill Forge gives the whole library one method. Each skill gets a purpose, a trigger, the right structure, a safe update process, and proof that it works before it counts as finished.

Five jobs, one system

1. Create a skill. Ask for a repeatable capability, such as invoice checks or customer research. Your agent designs it, waits for approval, builds it, tests the trigger, and runs one real task before calling it complete.
2. Create a scheduled workflow. Turn recurring work into a skill, a schedule, one reporting destination you choose, and a clear contract for what every run must report.
3. Update a skill. Add new knowledge without quietly removing the lessons and rules that already make the skill work.
4. Reorganize your library. Audit every existing skill, find overlaps and misplaced knowledge, propose the target structure, then refactor one skill at a time after you approve the roadmap.
5. Retire safely. Remove the schedule first when one exists, then archive the complete skill. Nothing is hard deleted, and every reference to the old skill is checked.

It designs before it writes

Before Skill Forge creates a file, it makes four decisions with you.

1. Purpose: what job does this skill own?
2. Trigger: what request or schedule should load it?
3. Structure: is it simple, a router with branches, or a step by step process?
4. Posture: should it advise the agent, or take control of the task?

You see the proposed name, trigger, structure, files, local setup, and data store before anything is built. You approve the shape first. The agent writes the files second.

That small pause prevents the expensive mistake: a well-written skill built in the wrong shape.

What a living skill looks like

Every skill gets one folder with clear boundaries:

your-skill/
  SKILL.md        the portable method and trigger
  CONTEXT.md      your paths, tools, accounts, and local setup
  LOGS.md         what ran, when, and what happened
  LEARNINGS.md    lessons a future run should keep
  references/     deeper knowledge, loaded only when needed
  scripts/        repeatable steps that should not be improvised
  assets/         templates and files used in the output

The method stays separate from your local setup, so the skill can move to another workspace without dragging private paths and business details with it.

The files make the loop visible. LOGS records the facts. LEARNINGS keeps only what future runs need. SKILL contains the proven method. CONTEXT holds the local setup that changes from one agent to another.

Mechanical work can become a script instead of a paragraph the agent interprets differently each time.

Already have a skills folder? Start there.

The strongest first use is not creating another skill. It is asking Skill Forge to audit the library you already have.

Your agent reads every skill, maps what each one does, finds overlaps, checks where local information is stored, and proposes one verdict for each: keep, update, merge, split, rename, or retire.

It writes the complete plan to a roadmap and stops. After you approve it, each original folder is archived before the refactor begins. The work happens one skill at a time, so an interrupted run can resume without guessing what changed.

At the end, you get a clean registry of every capability your agent has and when each one should load.

What is inside the download

The README sits outside the skill folder because it is written for your agent. Give it the ZIP and it handles the installation with you.

• README.mdthe agent onboarding guide, install order, first user menu, and dry test
• SKILL.mdthe complete five mode method for creating, updating, reorganizing, scheduling, and retiring skills
• references/taxonomy.mdthe four design decisions, with worked examples
• references/file-pattern.mdwhat belongs in each file and how skills stay portable
• references/engine-adapters.mddiscovery and scheduling for Claude Code, OpenClaw, Codex, and other file-reading agents
• references/workflow-contract.mdthe rules for scheduled work that nobody watches live
• references/testing.mdtrigger, real task, portability, secret, and clean workspace checks
• scripts/init_skill.pyan optional Python script that creates the standard folder structure
• CONTEXT · LOGS · LEARNINGSyour local setup, the run history, and lessons carried into future runs

Give the ZIP to your agent. It handles the rest with you.

Your agent reads the root README, moves the skill-forge folder into the correct skills directory, adds the discovery line to its boot file, and fills in the local context with you.

If an older skill creator already exists, your agent shows you the choice. It can keep both or archive the old one after your approval. Nothing is replaced silently.

The final install check is deliberately small. Ask your agent to create a test skill. It should propose the design across all four decisions and stop before writing files. If it writes immediately, the approval gate did not load correctly.

Skill Forge needs no extra API key or paid service. It runs through the agent you already use. Python 3 is optional. Git is recommended because it gives every change a clear history and rollback point.

What it refuses to do

It does not write a new skill before you approve its design.

It does not clean up an existing skill by silently deleting knowledge. It adds, moves, and reorganizes. If something looks wrong or outdated, it asks.

It does not call a workflow complete without the skill, schedule, reporting destination, and reporting rules. A scheduled job that runs silently is unfinished.

It does not hard delete retired skills. Originals move to an archive first.

It does not allow runtime notes to rewrite skills that govern behavior or style. Those need explicit human review.

Questions