AI Agents: Writing a Skill System From Scratch (Vibe-Coding the Cheshire Cat)

What gets crystallized, what stays open

Some viewers who aren’t especially technical tell me: “Look, watching you and others vibe-code, it clearly takes a ton of skills to actually do this.” And I’d say - a bit yes, a bit no. Over time this stuff gets crystallized where it should be crystallized, and left free and flexible where it’s right to keep it that way.

Take Lovable or Replit. They’re organizing things so that a user who doesn’t know much code gets the impression of building the whole application. In reality they’ve crystallized the backend with something like - not necessarily this, but similar to - Supabase: a solid, armored backend that lets you create tables and relations, with authentication, permissions, and everything already implemented. The vibe coder then mostly builds the front-end and the data structures they need on top.

That’s a hot question in itself: what do you crystallize, and what do you leave open?

What’s inside the project

Let me open the folders it created. Inside data there’s the uploads folder and, crucially, the SQLite database. There’s no more metadata.json; instead there’s an SQLite store that’s easy to extend. It holds both a per-user key-value store and a global key-value store, so in most cases you don’t even need to create tables - there are very simple APIs to use those key-value stores.

Under plugins you find several preinstalled plugins:

• Chat history archive - the Cat’s core keeps no conversation history and stores nothing itself; everything is saved outside. So you can save chats here, or disable this plugin and persist them wherever you like, with your own database.
• Language model plugins - Anthropic, Gemini, and so on, easy to add or remove; you can plug in local models like Llama too.
• The fake identity provider you saw earlier, which you can unplug and replace with a real one.
• Tutorial agents and example directives to chew on.

One example directive is the clock directive: it appends the current time to the system prompt so that, without calling a tool every time the prompt passes through the language model, the model always has the up-to-date time. Very useful these days - I know Anthropic already does something similar.

The graphical interface itself lives in a plugin, not in the Cat’s core, and so do the upload endpoints, which were extracted out of the core. What’s still missing is vector memory, and that’s deliberate - I haven’t put it into the Cat yet, because I think vector memory is increasingly a plus rather than a must. The RAG era already feels like it was twenty years ago. In reality RAG got encapsulated into tools, but that’s a longer discussion for another video. Write to me if you want to hear more about where RAG, vector DBs, agentic search, and file-system navigation all stand now.

Anatomy of a directive

The clock directive is a tiny class with three methods: start, step, and finish. The agent gets passed in, and you get to manipulate the agent, manipulate the tools, log things, ship data somewhere - observability, everything it’s doing. Guardrails, skills, dynamic tool modifications, vector memories, RAG - they’re all built as directives in Cheshire Cat 2.

The step method receives the agent on every step of the agentic loop. The system prompt is reset at every step, so the clock directive simply re-appends “current day, current time” each time, and the agent always knows what time it is. Dead simple.

Tools live on the class

Notice how tools work: inside the agent class you use a @tool decorator on an async function that takes self as its first argument. That self is useful for reaching other things inside the agent - a capability few frameworks have, because they usually frame a tool as a plain function. That plain-function framing never convinced me.

The notes agent it invented exposes read_notes, add_note, and clear_notes - a form of persistent memory. Look how clean the persistence is:

1
notes = await user.load("notes")   # per-user key-value store
2
notes.append(new_note)
3
await user.save("notes", notes)

You load from the specific user’s key-value store at the key notes (empty if nothing’s there), append, and save. If you want to store global things instead, you import store alongside user and call store.save(...). It’s genuinely easy

• and I nearly died making it this easy. But I’ve come to terms with the fact that almost nobody reads this code anymore, so at this point it’s better to make it easy so the agents understand it. And they do: the agent figured everything out in a few minutes, because the documentation itself is written for agents more than for people.

Trying the notes agent

I enable the pollo plugin, start a fresh conversation, and ask it to read my notes. First hiccup: the model I’d picked doesn’t support tool use - “no endpoints found that support tool use.” I swap models a couple of times (some giants like GLM, then a small Qwen 2.5 Coder) until one works.

It calls read_notes, finds the notebook empty, and reports back. I add two notes: one about taking someone’s mother out to dinner, another a note about the infinite beyond this hedge (a little Leopardi joke). If the model is good it fires both add_note calls in parallel; if it’s weak it does them in sequence. This one runs them in parallel - the Cat is fully async under the hood, which is why you see all those awaits. The two notes land in the database.

The nice proof: the Cat’s default agent has its own tools and no idea about these notes - ask it and it finds nothing. Only the pollo agent, which owns the notes tools, can read them back. Persistence confirmed.

How skills actually work

Here’s the plan I dictate to the agent. When the pollo agent has the skills directive, I expect the directive to do two things:

1. Look in a folder where the various skills live - each as a skill.md file.
2. Dynamically add a tool to the agent (without the agent having it hardcoded) that lets it open and read a skill.

And it needs to append to the system prompt the list of available skills. Because - let’s be honest - skills are kind of a silly, simple mechanism under the hood. That’s the beauty of it.

Concretely, the instructions I give:

• The default directory for skills is project_path/skills.
• The directive should append the list of skills to the system prompt so the agent knows which skills are available.
• It should add a tool so a skill can be opened by name; when the tool is called, the content of that skill is returned into the context.
• Also create an example skill for cooking Italian/Asian fusion cuisine.

I even prepare the folder myself: data/plugins/.../skills, a skills folder right inside the project. You have complete freedom over where to search for skills - the Cat can easily reach the project working directory, the plugin’s own directory, and the data directory where persistence lives, if you need custom behavior.

Progressive discovery: the whole point

Let me spell out why skills matter, because it’s easy to miss. When the agent starts, its system prompt already contains: who you are, what you do, these are the skills available to you, and these are your tools. Among the tools is an open_skill tool. The agent calls it with the name of a skill, and that tool does nothing more than go into the skills folder, read that specific skill.md, and inject its content into the context.

The essential advantage of skills is progressive discovery. At the start the agent knows only the names of the skills. Then it opens and reads a particular skill.md, which can point to further files and scripts, and it learns only what it needs to learn, when it needs to learn it. It gets more interesting when skills contain layered files of various kinds.

Reading the generated directive

The example skill it created is italo-asian-cuisine, complete with the typical skill front-matter (name, description) and instructions for gnocchi, tortellini, risotto, and the like.

The directive itself, in pollo/directives/skills.py, imports the base directive and the agent, plus config to reach config.project_path - the project’s root folder. It defines a couple of helper functions: one to parse the skill’s front-matter, one to get the directory where skills live. Both could easily become settings later - agents and directives can have settings that show up as little panels in the UI, so you could expose the skills folder as a configurable field.

The skills directive works like this:

• On start (before the loop), it looks up where the skills are, builds a catalog of each skill’s name and description, and appends to the system prompt: “You have access to the following skills. When you want to use one, call open_skill passing the skill’s name, and you’ll learn how it works.” Then it lists the skills. If there are no skills, it says so.
• It defines open_skill, the tool that opens a skill: it receives skill_name and reads the skill.md inside that folder. (It parses the file into front-matter plus body and returns the body - the file’s content - rather than reading it completely raw. Fine either way.)
• Because we’re inside a directive, the tool has to be added to the agent dynamically: agent.tools.append(...), building the tool on the fly from that function.

Why all this ceremony? Because if you build four different agents, some should support skills and others shouldn’t. You just add skills to a given agent’s directives and that agent is skill-capable - with the open_skill tool wired in automatically. Leave it off, and it isn’t. That’s the payoff of the directive abstraction.

It works

Back in the browser, still talking to the pollo agent, I ask: “What do you know about fusion cuisine? Give me your best recipes.”

The first thing it does is call open_skill, which returns the content of the skill.md; now the agent knows about that skill and reports back the recipes - yuzu risotto and friends. It even reads my saved notes on its own and adds a thoughtful aside: it noticed my note about taking someone’s mother to dinner and offers to add ingredients to the notebook. This is exactly the progressive discovery pattern: the agent knew all the skill names, opened only the one it cared about - you can see it passed skill_name: italo... - through a dedicated tool. It’s the same green “skill” dot you see light up when you use Claude Code: it fires the tool to read that skill’s skill.md header and body, which then points on to more.

(One thing worth a pull request if you feel like it: there’s currently no way to interrupt a running execution.)