1Why does my agent solve the same kind of task from scratch every time?
Because nothing it learned survives the run. A skill library keeps the small programs the agent wrote that actually worked, each with a description. The next task searches the library, reuses or combines stored skills, and only writes new code for what is missing.
You may need it if
- The agent writes nearly the same script every week, such as exporting a report or syncing two systems.
- Tasks are built from recurring steps that can be run and checked.
- Runs are slow and costly because every step is reasoned out anew.
2When is a library of skills not worth keeping?
Use it when
- Tasks can be solved by code that runs in a safe environment you control.
- Success can be checked from the run, such as a file produced or a test passed.
- Similar tasks come back often enough that reuse pays for the extra checking.
Avoid it when
- Tasks are rarely alike, so stored skills would almost never be reused.
Use ReAct instead - The reusable part is a sequence of steps in a user interface or a conversation, not something you can write as code.
Use Workflow Memory instead - The code touches real systems where a wrong run is costly. Gate each action before it runs.
Use Dry Run instead
What it costs
- Model calls
- 1 coding call + 1 check per attempt (at most 4), + 1 to file a new skill
- Latency
- high
- Complexity
- high
3How does a task turn into a tested skill that the next task can use?
The coder searches the library and writes a program, reusing stored skills where they fit. The program really runs. A checker reads the result and either sends the error back for another attempt or passes it. A curator files passing new code as a skill, then the result is released.
- Step 1 of 6
Look before writing
The coder searches the library by the task's description and gets the five closest skills. A recurring task may be solved by one call to a stored skill.
- Step 2 of 6
Write by composing
The coder writes a short program that calls the stored skills it needs and adds new code only for the missing step. The program is small, named and has clear inputs.
- Step 3 of 6
Run it for real
The runner executes the program in a sandbox. Nothing is judged on how plausible the code looks, only on what it did.
- Step 4 of 6
Check and retry
The checker compares the run's output with the task. On failure, the error message goes back to the coder, which fixes the code. Four attempts at most.
- Step 5 of 6
Keep what worked
If the passing program contains new code, the curator writes a one-line description and files it as a skill. Failed programs are never filed.
- Step 6 of 6
Release the result
The result leaves with the run's output, the skills used, any skill added, and a plain statement of success or of the last error after four attempts.
What each part does
- Task
- The task to accomplish, stated so that success can be checked.
- Skill library
- Tested programs, each with a description, its inputs and the skills it calls, searchable by description.
- Coder
- Finds relevant skills and writes a program that calls them, adding new code only for what is missing.
- Runner
- Executes the program in a sandbox and captures its output, errors and effects.
- Task done?
- Reads the run's output and decides whether the task was achieved, counting the attempts used.
- Curator
- Describes the working program and files it, so future tasks can find and reuse it.
- Result
- The outcome of the run and the answer, with the skills used and whether the task succeeded.
- Skill library → Coder: closest skills
- Coder → Runner: program
- Runner → Task done?: output and errors
- Task done? → Coder: failed, attempts left
- Task done? → Curator: passed with new code
- Task done? → Result: passed with stored skills, or attempts spent
- Curator → Skill library: new skill
Where it connects
A task that code can accomplish, with a way to tell from the run whether it succeeded.
When: The checker passed the run, or four attempts failed.
Whether the task succeeded, the run's output and effects, the skills used, any new skill filed, and the last error on failure.
Programs that passed a real run, each with a description, inputs, the skills it calls and the date last verified.
4What do I ask my assistant to set up?
The agents to launch
Coder
Solve the task with a short program. First reuse the skills provided, calling them by name. Write new code only for steps no skill covers, as small functions with clear inputs. On a retry, fix the reported error and change nothing else.
Sees: The task, the five closest skills with their descriptions and code, and on a retry the last program and its error. Not the whole library.
Checker
Decide whether the task was achieved, using only the run's output, errors and effects. Answer pass or fail with one reason. On fail, say what the output shows went wrong. Do not suggest code.
Sees: The task and the run's output, errors and effects. Not the program and not the coder's reasoning.
Curator
For the passing program, name each new function, write a one-line description of what it does and when to use it, and list its inputs and the skills it calls. Reject the filing if an existing skill already does the same thing.
Sees: The task, the passing program and the descriptions of existing skills. Not the failed attempts.
A prompt you can paste
Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.
You are the orchestrator of a multi-agent workflow that follows the "Skill Library" architecture. Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it. # Task [Describe your task here] # Skill Library Write a program, prove it works, keep it, and build on it next time. Input: the task above. It must provide: A task that code can accomplish, with a way to tell from the run whether it succeeded. If something essential is missing, ask for it before starting. Agents to launch: - Coder: Solve the task with a short program. First reuse the skills provided, calling them by name. Write new code only for steps no skill covers, as small functions with clear inputs. On a retry, fix the reported error and change nothing else. Context for this agent: The task, the five closest skills with their descriptions and code, and on a retry the last program and its error. Not the whole library. - Checker: Decide whether the task was achieved, using only the run's output, errors and effects. Answer pass or fail with one reason. On fail, say what the output shows went wrong. Do not suggest code. Context for this agent: The task and the run's output, errors and effects. Not the program and not the coder's reasoning. - Curator: For the passing program, name each new function, write a one-line description of what it does and when to use it, and list its inputs and the skills it calls. Reject the filing if an existing skill already does the same thing. Context for this agent: The task, the passing program and the descriptions of existing skills. Not the failed attempts. Procedure: 1. Set up a sandbox where programs can run safely, and a library store that can be searched by description. 2. Search the library with the task description and keep the five closest skills. 3. Launch the coder with the task and those skills. Run its program in the sandbox and capture the output. 4. Launch the checker in a fresh context on the task and the run's output. On fail, give the error back to the coder and run again, up to four attempts. 5. On pass with new code, launch the curator and file the skills it describes. Mark every reused skill as verified today. 6. Release the result with the outcome, the skills used and any skill added. Stop rule: Stop when the checker passes a run, or after four attempts. Only programs that passed are ever written to the library. Exit: - `result`, when: The checker passed the run, or four attempts failed. Deliver: Whether the task succeeded, the run's output and effects, the skills used, any new skill filed, and the last error on failure. # Final deliverable Success or failure, the run's output, the skills reused, the skills added with their descriptions, and the last error if all attempts failed.
The same thing in code
from datetime import date
from typing import Literal, TypedDict
from langchain.chat_models import init_chat_model
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel
llm = init_chat_model("anthropic:claude-sonnet-5-5")
MAX_ATTEMPTS = 4
class Skill(BaseModel):
name: str
description: str
inputs: list[str]
calls: list[str]
code: str
verified: str = ""
class Program(BaseModel):
code: str
reused: list[str]
new_functions: list[str]
class Check(BaseModel):
passed: bool
reason: str
class Filing(BaseModel):
skills: list[Skill]
class RunOutput(TypedDict):
output: str
errors: str
effects: str
library: list[Skill] = [] # stand-in for a store searchable by description
def closest(task: str, k: int = 5) -> list[Skill]:
return library[:k] # plug in embedding search over skill descriptions
def run_in_sandbox(code: str) -> RunOutput:
return {"output": "", "errors": "", "effects": ""} # plug in a sandbox (container, microVM)
class State(TypedDict):
task: str
skills: list[Skill]
program: Program | None
run: RunOutput | None
check: Check | None
attempts: int
async def ask[T: BaseModel](schema: type[T], prompt: str) -> T:
out = await llm.with_structured_output(schema).ainvoke(prompt)
assert isinstance(out, schema)
return out
def retrieve(state: State) -> dict:
return {"skills": closest(state["task"])}
async def coder(state: State) -> dict:
# the coder sees five skills and, on a retry, only the last program and its error
shown = "\n\n".join(f"# {s.name}: {s.description}\n{s.code}" for s in state["skills"])
retry = ""
if state["program"] and state["check"]:
retry = f"\n\nLast program:\n{state['program'].code}\nWhat went wrong: {state['check'].reason}\n{state['run']}"
p = await ask(Program, "Solve the task with a short program. Reuse the skills below by name; write new code "
"only for missing steps, as small functions. On a retry, fix the reported error and change "
f"nothing else.\n\nTask: {state['task']}\n\nSkills:\n{shown}{retry}")
return {"program": p, "attempts": state["attempts"] + 1}
def runner(state: State) -> dict:
assert state["program"]
return {"run": run_in_sandbox(state["program"].code)}
async def checker(state: State) -> dict:
# fresh context: the task and the run, not the program or the coder's reasoning
c = await ask(Check, "Decide whether the task was achieved, from the run's output, errors and effects only. "
f"Pass or fail with one reason. Do not suggest code.\n\nTask: {state['task']}\nRun: {state['run']}")
return {"check": c}
def task_done(state: State) -> Literal["coder", "curator", "__end__"]:
assert state["check"] and state["program"]
if state["check"].passed:
return "curator" if state["program"].new_functions else "__end__"
return "coder" if state["attempts"] < MAX_ATTEMPTS else "__end__" # the gate: 4 attempts
async def curator(state: State) -> dict:
assert state["program"]
known = "\n".join(f"{s.name}: {s.description}" for s in library)
f = await ask(Filing, "For each new function in the passing program, give its name, a one-line description "
"of what it does and when to use it, its inputs, the skills it calls and its code. Leave out "
f"any that an existing skill already covers.\n\nTask: {state['task']}\n"
f"Program:\n{state['program'].code}\n\nExisting skills:\n{known}")
library.extend(s.model_copy(update={"verified": date.today().isoformat()}) for s in f.skills) # only passing code
return {}
g = StateGraph(State)
g.add_node("retrieve", retrieve)
g.add_node("coder", coder)
g.add_node("runner", runner)
g.add_node("checker", checker)
g.add_node("curator", curator)
g.add_edge(START, "retrieve")
g.add_edge("retrieve", "coder")
g.add_edge("coder", "runner")
g.add_edge("runner", "checker")
g.add_conditional_edges("checker", task_done)
g.add_edge("curator", END)
app = g.compile()
async def run(task: str):
s = await app.ainvoke({"task": task, "skills": [], "program": None, "run": None, "check": None, "attempts": 0})
passed = bool(s["check"] and s["check"].passed)
if passed and s["program"]:
for skill in library:
if skill.name in s["program"].reused:
skill.verified = date.today().isoformat()
return {"passed": passed, "run": s["run"], "attempts": s["attempts"], "program": s["program"]}
Replace run_in_sandbox with a real isolated sandbox and closest with embedding search; never run generated code on a machine with real data.
import json
from datetime import date
from typing import Any
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
MAX_ATTEMPTS = 4
library: list[dict[str, Any]] = [] # stand-in for a store searchable by description
def closest(task: str, k: int = 5) -> list[dict[str, Any]]:
return library[:k] # plug in embedding search over skill descriptions
def run_in_sandbox(code: str) -> dict[str, str]:
return {"output": "", "errors": "", "effects": ""} # plug in a sandbox (container, microVM)
AGENTS = {
"coder": AgentDefinition(
description="Writes a short program that reuses stored skills.",
prompt="Solve the task with a short program. Reuse the skills provided by name. Write new code only for "
"steps no skill covers, as small functions. On a retry, fix the reported error and change "
"nothing else.", tools=[]),
"checker": AgentDefinition(
description="Decides from a run's output whether the task was achieved.",
prompt="Decide whether the task was achieved, using only the run's output, errors and effects. Answer "
"pass or fail with one reason. Do not suggest code.", tools=[]),
"curator": AgentDefinition(
description="Describes and files new functions from a passing program.",
prompt="For each new function in the passing program give its name, a one-line description of what it "
"does and when to use it, its inputs, the skills it calls and its code. Skip any that an "
"existing skill already covers.", tools=[]),
}
def obj(**props: Any) -> dict[str, Any]:
return {"type": "object", "required": list(props), "properties": props}
S, L = {"type": "string"}, {"type": "array", "items": {"type": "string"}}
PROGRAM = obj(code=S, reused=L, new_functions=L)
CHECK = obj(passed={"type": "boolean"}, reason=S)
FILING = obj(skills={"type": "array", "items": obj(name=S, description=S, inputs=L, calls=L, code=S)})
async def delegate(agent: str, payload: str, schema: dict[str, Any]) -> Any:
# one query per step: each sub-agent starts from a fresh context
options = ClaudeAgentOptions(agents=AGENTS, allowed_tools=["Agent"],
output_format={"type": "json_schema", "schema": schema})
prompt = f"Use the {agent} agent on the input below and return its reply unchanged.\n\n{payload}"
async for msg in query(prompt=prompt, options=options):
if isinstance(msg, ResultMessage):
return msg.structured_output
async def run(task: str):
skills = closest(task)
shown = json.dumps([{k: s[k] for k in ("name", "description", "code")} for s in skills])
retry, program, result, check = "", {}, {}, {"passed": False, "reason": ""}
for attempt in range(1, MAX_ATTEMPTS + 1): # the gate: 4 attempts
program = await delegate("coder", f"Task: {task}\n\nSkills: {shown}{retry}", PROGRAM)
result = run_in_sandbox(program["code"]) # the program really runs
# the checker sees the task and the run, not the program
check = await delegate("checker", f"Task: {task}\n\nRun: {json.dumps(result)}", CHECK)
if check["passed"]:
break
retry = f"\n\nLast program:\n{program['code']}\n\nError: {check['reason']}\n{result['errors']}"
added: list[str] = []
today = date.today().isoformat()
if check["passed"]:
for s in skills:
if s["name"] in program["reused"]:
s["verified"] = today
if program["new_functions"]: # only passing code is ever filed
known = "\n".join(f"{s['name']}: {s['description']}" for s in library)
filing = await delegate("curator", f"Task: {task}\n\nProgram:\n{program['code']}\n\n"
f"Existing skills:\n{known}", FILING)
library.extend({**s, "verified": today} for s in filing["skills"])
added = [s["name"] for s in filing["skills"]]
return {"passed": check["passed"], "run": result, "reused": program.get("reused", []), "added": added,
"attempts": attempt, "last_error": "" if check["passed"] else check["reason"]}
Replace run_in_sandbox with a real isolated sandbox and closest with embedding search; never run generated code on a machine with real data.
from datetime import date
from agents import Agent, Runner
from pydantic import BaseModel
MAX_ATTEMPTS = 4
class Skill(BaseModel):
name: str
description: str
inputs: list[str]
calls: list[str]
code: str
verified: str = ""
class Program(BaseModel):
code: str
reused: list[str]
new_functions: list[str]
class Check(BaseModel):
passed: bool
reason: str
class Filing(BaseModel):
skills: list[Skill]
library: list[Skill] = [] # stand-in for a store searchable by description
def closest(task: str, k: int = 5) -> list[Skill]:
return library[:k] # plug in embedding search over skill descriptions
def run_in_sandbox(code: str) -> str:
return "" # plug in a sandbox (container, microVM); return output, errors and effects
coder = Agent(name="Coder", output_type=Program,
instructions="Solve the task with a short program. Reuse the skills provided by name. Write new "
"code only for steps no skill covers, as small functions. On a retry, fix the "
"reported error and change nothing else.")
checker = Agent(name="Checker", output_type=Check,
instructions="Decide whether the task was achieved, using only the run's output, errors and "
"effects. Pass or fail with one reason. Do not suggest code.")
curator = Agent(name="Curator", output_type=Filing,
instructions="For each new function in the passing program give its name, a one-line "
"description of what it does and when to use it, its inputs, the skills it calls "
"and its code. Skip any that an existing skill already covers.")
async def run(task: str):
skills = closest(task)
shown = "\n\n".join(f"# {s.name}: {s.description}\n{s.code}" for s in skills)
retry, output = "", ""
program, check = Program(code="", reused=[], new_functions=[]), Check(passed=False, reason="")
for attempt in range(1, MAX_ATTEMPTS + 1): # the gate: 4 attempts
program = (await Runner.run(coder, f"Task: {task}\n\nSkills:\n{shown}{retry}")).final_output_as(Program)
output = run_in_sandbox(program.code) # the program really runs
# the checker sees the task and the run, not the program
check = (await Runner.run(checker, f"Task: {task}\n\nRun:\n{output}")).final_output_as(Check)
if check.passed:
break
retry = f"\n\nLast program:\n{program.code}\n\nError: {check.reason}"
today, added = date.today().isoformat(), []
if check.passed:
for s in skills:
if s.name in program.reused:
s.verified = today
if program.new_functions: # only passing code is ever filed
known = "\n".join(f"{s.name}: {s.description}" for s in library)
filing = await Runner.run(curator, f"Task: {task}\n\nProgram:\n{program.code}\n\nExisting:\n{known}")
added = [s.model_copy(update={"verified": today}) for s in filing.final_output_as(Filing).skills]
library.extend(added)
return {"passed": check.passed, "output": output, "reused": program.reused,
"added": [s.name for s in added], "attempts": attempt, "last_error": "" if check.passed else check.reason}
Replace run_in_sandbox with a real isolated sandbox and closest with embedding search; never run generated code on a machine with real data.
import { anthropic } from '@ai-sdk/anthropic';
import { generateText, Output } from 'ai';
import { z } from 'zod';
const model = anthropic('claude-sonnet-5-5');
const MAX_ATTEMPTS = 4;
const Skill = z.object({
name: z.string(),
description: z.string().describe('what it does and when to use it'),
inputs: z.array(z.string()),
calls: z.array(z.string()),
code: z.string(),
});
type Skill = z.infer<typeof Skill> & { verified: string };
const Program = z.object({ code: z.string(), reused: z.array(z.string()), newFunctions: z.array(z.string()) });
const Check = z.object({ passed: z.boolean(), reason: z.string() });
const library: Skill[] = []; // stand-in for a store searchable by description
function closest(task: string, k = 5): Skill[] {
return library.slice(0, k); // plug in embedding search over skill descriptions
}
async function runInSandbox(code: string): Promise<string> {
return ''; // plug in a sandbox (container, microVM); return output, errors and effects
}
export async function run(task: string) {
const skills = closest(task);
const shown = skills.map((s) => `// ${s.name}: ${s.description}\n${s.code}`).join('\n\n');
let retry = '';
let output = '';
let program: z.infer<typeof Program> = { code: '', reused: [], newFunctions: [] };
let check: z.infer<typeof Check> = { passed: false, reason: '' };
let attempt = 0;
while (attempt < MAX_ATTEMPTS) { // the gate: 4 attempts
attempt++;
({ output: program } = await generateText({
model,
output: Output.object({ schema: Program }),
instructions:
'Solve the task with a short program. Reuse the skills provided by name. Write new code only for ' +
'steps no skill covers, as small functions. On a retry, fix the reported error and change nothing else.',
prompt: `Task: ${task}\n\nSkills:\n${shown}${retry}`,
}));
output = await runInSandbox(program.code); // the program really runs
// the checker sees the task and the run, not the program
({ output: check } = await generateText({
model,
output: Output.object({ schema: Check }),
instructions:
"Decide whether the task was achieved, using only the run's output, errors and effects. " +
'Pass or fail with one reason. Do not suggest code.',
prompt: `Task: ${task}\n\nRun:\n${output}`,
}));
if (check.passed) break;
retry = `\n\nLast program:\n${program.code}\n\nError: ${check.reason}`;
}
const today = new Date().toISOString().slice(0, 10);
let added: Skill[] = [];
if (check.passed) {
for (const s of skills) if (program.reused.includes(s.name)) s.verified = today;
if (program.newFunctions.length) { // only passing code is ever filed
const { output: filing } = await generateText({
model,
output: Output.object({ schema: z.object({ skills: z.array(Skill) }) }),
instructions:
'For each new function in the passing program give its name, a one-line description of what it ' +
'does and when to use it, its inputs, the skills it calls and its code. Skip any an existing skill covers.',
prompt: `Task: ${task}\n\nProgram:\n${program.code}\n\nExisting:\n${library.map((s) => `${s.name}: ${s.description}`).join('\n')}`,
});
added = filing.skills.map((s) => ({ ...s, verified: today }));
library.push(...added);
}
}
return { passed: check.passed, output, reused: program.reused, added: added.map((s) => s.name), attempts: attempt,
lastError: check.passed ? '' : check.reason };
}
Replace runInSandbox with a real isolated sandbox and closest with embedding search; never run generated code on a machine with real data.
Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.
What goes wrong
- Filing code that was never run turns the library into a collection of guesses. File only after a passing run.
- Vague descriptions make skills impossible to find later. Describe what the skill does and when to use it.
- Without a sandbox, a retry loop of untested code can damage real data.
- Skills that call changing systems go stale. Re-verify on use and retire skills that keep failing.
Chain it
This architecture stands alone: the compatibility matrix allows no link into or out of it.