Skill Libraries

In plain words

Imagine a senior who explains the same IRCTC booking trick to every junior, then finally writes it down once. Agents should do the same. When an agent works something out and it actually works, save it as named code with a short description. Next time a similar task comes, search the library, pull those skills, and join them into a bigger one.

How it flows

A tiny example

task = "craft an iron pickaxe"
found = library.search(task, k=3)
skill = write_skill(task, found)
signal = run(skill)
if signal == "success":
    library.register(skill)
else:
    skill = refine(skill, signal)

Notice that a new skill is written from skills already found in the library, and the failure signal is what feeds the rewrite.

What you will learn

• Why an agent should save what it learns as reusable code, not throw it away.
• The three parts of a skill library agent: curriculum, library, refinement loop.
• How skills get stored, found again, and joined together into bigger skills.
• Where this same idea shows up in real tools you already use.

The problem, simply

Think about your first year hostel senior, Karthik. Every Sunday he used to explain the same thing to juniors: how to book a ticket on IRCTC during Diwali rush, which quota to pick, when the tatkal window opens. Same explanation, forty times, to forty juniors.

One day he got tired and wrote it down once in a shared doc. Next Diwali, nobody asked him again. They just read it and followed it.

See, most AI agents behave like Karthik before the doc. Every session they figure out the same thing from zero. You ask an agent to clean a CSV file on Monday, it works out a method. You ask again on Thursday, fresh session, and it works out the same method again from scratch.

Three things go wrong. You pay tokens for the same thinking again and again. Any correction you gave on Monday is lost by Thursday. And big tasks become impossible, because a big task is ten small tasks stacked, and the agent saved none of them.

The idea

The fix is simple to say: whenever the agent works something out and it actually works, save it as a named piece of code. Later, when a similar task comes, find that code and reuse it.

This idea got famous through a 2023 research project called Voyager, which put an agent inside Minecraft with no human instructions. It collected more than three times as many unique items as earlier agents, and reached stone tools about eight times faster. Those are Minecraft numbers, but the pattern travels everywhere.

Three parts

Voyager has three moving parts. Learn these names, interviewers ask.

1. Automatic curriculum — a small planner that looks at what the agent can already do and proposes the next task, one step above current ability. Not too easy, not impossible.
2. Skill library — a store of skills. A skill is a named function plus a one-line description of what it does.
3. Iterative prompting — when a skill fails, the agent gets the failure details back and rewrites the skill. Then tries again.

The action is code, not a command

This is the part people miss. Most agents output tiny commands: "move left", "click button". Voyager outputs a whole function.

So instead of saying "mine iron, mine iron, place table, craft", it writes one function called craftIronPickaxe that calls mineIron and placeCraftingTable — skills it saved earlier. Basically, a skill can call other skills. That is how small abilities grow into big ones.

IMP

Note: A skill is stored as text of code plus a plain-English description. The description is what makes it findable later; the code is what makes it useful.

Finding the right skill again

Suppose Priya's agent gets a new task: "make a diamond pickaxe". The agent does not scan all 400 saved skills. It does this:

1. Takes the task description, "make a diamond pickaxe".
2. Searches the library for the most similar descriptions, say the top 5.
3. Gets back craftIronPickaxe, mineDiamond, placeCraftingTable.
4. Writes a new small function that calls those three, plus a little new logic.
5. If it works, saves it as craftDiamondPickaxe.

Notice the agent wrote maybe six new lines. Everything else was already earned.

When it fails

Running a skill gives back exactly one of three signals. Remember: success, error with the stack trace, or self-verification failure — meaning it ran without crashing but the goal was not actually achieved.

All three go straight back into the prompt for the next attempt. Version 2 of the skill is written knowing exactly why version 1 broke.

Where it goes wrong in real projects

• Library rot. The same skill lands ten times with slightly different descriptions. Search then returns ten near-copies and the agent picks randomly. Fix: check for near-duplicates before writing, keep one canonical version.
• Composed-skill drift. Skill A calls skill B. Someone refines B to version 3. Now A silently behaves differently and nobody tested that. Fix: pin versions — A depends on B@1, not "whatever B is today".
• Retrieval quality. Similarity search over descriptions works fine for fifty skills. Past a few hundred it gets sloppy. Fix: add tags and hard filters, like "only skills tagged database".

Build it

Here is a small skill library in plain Python. Save it and run it.

"""A tiny Voyager-style skill library: register, search, compose, refine."""

class Skill:
    def __init__(self, name, description, code, tags=(), deps=()):
        self.name, self.description = name, description
        self.code, self.tags, self.deps = code, list(tags), list(deps)
        self.version = 1

class SkillLibrary:
    def __init__(self):
        self.skills = {}

    def register(self, skill):
        # Dedup on write: same description means we keep the old one.
        for old in self.skills.values():
            if old.description.lower() == skill.description.lower():
                print(f"  skip duplicate of {old.name}")
                return old
        self.skills[skill.name] = skill
        print(f"  saved {skill.name}@v{skill.version}")
        return skill

    def search(self, query, k=3):
        # Cheap retrieval: count how many words the descriptions share.
        words = set(query.lower().split())
        scored = []
        for s in self.skills.values():
            overlap = len(words & set(s.description.lower().split()))
            if overlap:
                scored.append((overlap, s))
        scored.sort(key=lambda pair: -pair[0])
        return [s for _, s in scored[:k]]

    def compose(self, name, description, deps):
        # A new skill that just calls the ones it depends on, in order.
        body = "\n".join(f"    {d}()" for d in deps)
        return self.register(Skill(name, description, f"def {name}():\n{body}", deps=deps))

    def refine(self, name, signal, new_code):
        skill = self.skills[name]
        skill.version += 1
        skill.code = new_code
        print(f"  refined {name} to v{skill.version} because: {signal}")
        return skill

lib = SkillLibrary()
print("Registering primitives:")
for n, d in [("mine_iron", "mine iron ore blocks"),
             ("make_stick", "make wooden stick items"),
             ("place_table", "place a crafting table")]:
    lib.register(Skill(n, d, f"def {n}():\n    return '{n} done'"))

print("\nSearch for 'craft an iron pickaxe with a table':")
found = lib.search("craft an iron pickaxe with a table")
print("  retrieved:", [s.name for s in found])

print("\nComposing a new skill from what we found:")
pickaxe = lib.compose("craft_iron_pickaxe", "craft an iron pickaxe tool",
                      [s.name for s in found])

print("\nRunning it... failure signal comes back:")
lib.refine("craft_iron_pickaxe", "self-verification failed: no table nearby",
           pickaxe.code.replace("mine_iron()", "place_table()\n    mine_iron()"))
print("\nFinal library:", {s.name: s.version for s in lib.skills.values()})

Look at three things in the output. First, retrieval returns only the skills whose descriptions share words with the task, not the whole library. Second, the composed skill is just a call list — no new logic was invented. Third, the failure signal is what drives the jump to version 2.

Where you will see this

• Claude Code and the Claude Agent SDK let you define skills: a name, a description, and instructions or code the agent loads only when the task needs it.
• Cursor and similar coding tools keep project rules and saved patterns so they do not relearn your codebase style every session.
• Customer support bots keep a growing set of resolved-issue playbooks and pull the matching one instead of improvising.
• Internal team agents at companies build domain skill sets — SQL skills for a data team, deployment skills for an infra team.
• Even a plain tool list in an agent framework is the small version of this: each tool is a tiny skill with a description.

Common mistakes

• Saving every attempt, including the failed ones. Your library fills with broken code that retrieval happily returns later. Only write on verified success.
• No description discipline. If descriptions are vague like "helper function", search cannot find anything. The description is the index, treat it seriously.
• Skipping version pinning. A parent skill quietly changes behaviour when a child is refined, and you debug for two days.
• Retrieving too many skills. Stuffing fifteen skills into the prompt wastes context and confuses the model. Top three to five is usually enough.
• No dedup check. Ten copies of the same skill with different names looks harmless until retrieval starts choosing badly.

If they ask in an interview

Q: What is a skill library in an agent, and why is it better than just a long prompt?

A: A skill library stores verified capabilities as named code with descriptions, so the agent fetches only what the current task needs. A long prompt has to carry everything at once, costs more tokens, and cannot grow across sessions. The library also lets skills call each other, which a prompt cannot express cleanly.

Q: Voyager makes the action space code instead of primitive commands. What does that buy you?

A: One function can express a long sequence of actions, so the agent plans at a higher level instead of one step at a time. Code is also composable and reusable — a saved function becomes a building block for the next task. Primitive commands have to be re-derived every single time.

Q: How do you stop a skill library from degrading as it grows?

A: Deduplicate on write so near-identical descriptions collapse into one canonical skill, and pin versions so a refined child does not silently change its parent. Add tags and filters on top of similarity search, because plain similarity gets unreliable past a few hundred skills.

Try these

1. Add a cycle detector to compose. If skill A depends on B and B depends on A, should it raise an error or just warn? Decide and implement it.
2. Implement version pinning. Store dependencies as place_table@1 and make refine leave the parent on the old version until you explicitly upgrade it.
3. Replace the word-overlap search with a slightly better one — for example, weight rare words higher. Build a toy library of thirty skills and check how often the right skill lands in the top five.
4. Write a small "curriculum" function: given the library and a domain like "data cleaning", print five skills that are missing. Run it by hand once a week on your own project.

Words, simply

Quick recap

• Save what works as named code, not as throwaway reasoning — then find it again by description.
• Skills call other skills, so small verified abilities stack into large ones.
• Failure signals are the fuel: error, crash trace, or goal-not-met all feed the next version.