Storing AI agent skills as files in a folder does not scale. Claude Code skills, your claude.md instructions, and every other slice of your agent’s memory eventually rots, conflicts, or eats the context window. A better pattern is to store each skill as a document in a semantic memory store, tagged by topic and date. Searching by tag returns the latest version; older versions stay for audit and rollback.
The problem, concretely
Say you teach your agent how to clean up old Docker containers on a server. Six steps, two gotchas. You write a server-cleanup skill, a markdown file dropped into your skills directory.
Three months later the underlying CLI changes. The skill is still valid for 80% of cases, but step 4 needs updating. You have three options:
- Edit the file in place. You lose the old version. If the new one breaks, there is no clean rollback.
- Create
server-cleanup-v2.md. Now you have two files. Which one does the agent use? Both? You add logic to pick, and filenames start carrying version semantics. - Do not touch it. The skill silently rots. Next time you use it, you waste twenty minutes debugging a change you never made.
None of these is good. The first loses history. The second creates a maintenance pipeline you did not sign up for. The third creates dead code indistinguishable from live code.
Why file-based skills fail at scale
Eager preload. Load every skill description into the system prompt. Fast lookup, no extra reads. At 50 skills that is 5-8K tokens eaten before any work starts. At 200 skills you have consumed half your context window, and every prompt pays it.
Lazy load through an index. Keep a flat index of names, read the body when needed. Better on tokens, but every task triggers one to three exploration reads. The agent reads the index, picks the wrong skill, reads another, reads the index again.
Neither has a gardener mode. Nobody removes old skills. Nobody flags duplicates. Six months in you have 70 skills, 30 stale, 20 overlapping, and no system to tell you which.
The pattern: skills as memory documents
Instead of files, store each skill as a document in a semantic memory store. Tag it:
type:skill topic:server-cleanup date:2026-05-22 version:1 The body is the skill: preconditions, steps, postconditions, gotchas. When you need it, search by tags:
mesh_bytag(tags=["type:skill", "topic:server-cleanup"]) You get every version, newest first. Take the latest.
When the skill needs updating you do not edit. You add a new document with today’s date. The old one stays, visible in history and available for rollback, but no longer surfaces first.
What this solves
Versioning is automatic. Date in the tag, latest wins. No v1/v2/v3 filename juggling.
Deprecation is free. Old skills are superseded rather than deleted. Zero risk of removing something still needed.
Discoverability scales. Semantic search across thousands of documents costs one query. No agent walks an index.
Conflict detection. If two skills overlap, the search returns both. Duplicates surface naturally.
Audit history is built in. Filter by topic, sort by date, and you can see how a procedure evolved.
Federation: one workspace per agent
If you run several agents, give each its own workspace:
workspaces/ dev/ skills + snapshots for development ops/ skills + snapshots for ops content/ skills + snapshots for content shared/ cross-agent knowledge Each agent owns its own garden. When a skill is genuinely shared, a deploy routine both agents use, it goes in the shared workspace tagged with the project name.
This has a property file-based approaches do not: the gardener problem becomes tractable. Maintaining a central repo of 200 skills is nobody’s job. Maintaining your own workspace of 30 is achievable.
A concrete example
Write the skill the first time:
mesh_add( content="# Web App Deploy ...", tags=["type:skill", "topic:web-deploy", "date:2026-05-22"] ) In your agent’s instructions, write a thin pointer:
When working on web-deploy: search mesh_bytag for type:skill + topic:web-deploy use the most recent version That is it. No more rules in your global instructions; the agent fetches the live procedure when it needs it.
Six months later a fix lands. Write v2:
mesh_add( content="# Web App Deploy v2 ...", tags=["type:skill", "topic:web-deploy", "date:2026-11-15", "supersedes:doc_xyz"] ) The same call now returns v2 first. v1 is still there, still searchable, still available to roll back to.
What this means if you are building agents
If your instructions file is growing past the point where you can read it in one sitting, that is the signal. Skill files do not scale linearly, they scale catastrophically.
The key shift is treating accumulated agent memory as data rather than as code: versioned, tagged, searchable, and deprecated through supersession rather than deletion.
mesh-memory is MIT licensed, runs in Docker, and ships with an MCP server, so Claude Code, Cursor and other MCP-aware agents can talk to it directly.
Repository: https://github.com/dklymentiev/mesh-memory
Originally published at https://klymentiev.com/blog/claude-skills-as-memory