published
I devised a skill system that is simple, sharable, and cross-platform. All it took was flat files. An example implementation is open source here. This article is about what limitations it solves for and how it works.
Anthropic introduced skills in October 2025 and in December they published Agent Skills as an open standard. The idea makes sense. Taking complex instruction sets and saving them in a standardized format for repeatability. It is Programming 101; it is abstraction and encapsulation. It was promising! The open standard fertilizes the ecosystem for creating and sharing skills cross-platform. So, when I started using skills in March, I was the #1 promoter of skills in my org for about 2 weeks and then...
I realized that they are notoriously inconsistent and hard to share. One year on, the standard and providers continue to struggle with this lack of ergonomics, making life hard for users.
For example, here are some basic capabilities you might expect from Agent Skills:
- Using the same skill in multiple projects
- Using a certain context file in multiple skills
- Iterating on shared skills and updating them
These are possible. But they are complicated and easy to mess up. They involve manual (or agentic) copy-paste. The difficulty scales with the size of your skills library.
These gaps start to sting when you adopt Agent Skills in your workflows, and they get magnified when you start trying to share skills across teams and organizations. Which ironically is also the promise of Skills! If done right, Skills can be an organizational multiplier. Experts can train skills to be accurate, and introspect on them to make them time and token efficient. Then the skills can be shared across the org for people to use, and iterations can be approved by experts. This is the killer use case. Unfortunately, people dread using skills in organizations.
The current framework makes it difficult to share skills and context between individuals and departments. Shared skill management is complicated. Skills drift because people's local copies of skills drift. Plugins are opaque. Reading and iterating on shared skills is hard, so no one does it. The Agent Skills framework simply lacks the agility for supporting organizations. Why?
The root cause
Its all about the folder structure. This is how Agent Skills standard expects information to be stored.
These are all distinct from each other while in reality, information is interconnected. Like so...
Same skills, same files, but more...natural.
So how do we get from the nested/hierarchical structure to the interconnected structure? First we must understand the problem.
Agent Skills standard forces each skill to be protective of its knowledge, scripts, agents, references, whatever.
.skills/
└── my-skill-1/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
└── my-skill-2/
├── SKILL.md # Required: metadata + instructions
├── references/ # Optional: documentation
└── ... # Any additional files or directories
-
This is divorced from how information works. It makes every skill the master of its own truth. While in reality, there is opinionated truth that should be shared between skills. The current structure ultimately forces inconsistency when all skills may have a different sense of the truth - like what your org structure is, for example - because they were all updated at different times by different people.
-
It forces a hierarchy. Skills become the top of the food chain alongside agents. Everything else is demoted, and duplicated over and over again inside of every other skill that needs it.
-
It breaks the promise of abstraction. This gives users a taste of repeatability, but doesn't go all the way. There is repeatability in the sense that you can use the same skill over and over, but no repeatability in maintenance/sharing context between skills.
The thing is, LLMs don't need this organization. This organization is for humans. But humans aren't the ones reading these files. People are more likely to evaluate a skill based on output quality, session history, tool call history, and token efficiency. That doesn't mean the skill itself should be obfuscated from the user. Users want to read skills for transparency, peace of mind, debugging, iteration. However, no one is navigating their file system to read skills. So why build for the traditional file system?
The system design has the wrong affordances. Its like the industry built a humanoid robot to drive the car instead of building a self-driving car. I've talked about a similar concept in my article: Programming Languages and Computer Languages
The current structure sacrifices flexibility and sharability for some kind of warped user friendliness that it fails to achieve. This is not the intractable contradiction it appears to be. We can have it all.
Flat Files and Frontmatter
I propose storing skills in flat file structure like so:
.skills/
├── SKILLS/
├── skill-1
└── skill-2
├── AGENTS/
├── query-agent
└── agent-2
├── KNOWLEGE/
├── knowledge-1
├── knowledge-2
└── org-context
├── SCRIPTS/
└── script-1
├── ASSETS/
└── asset-1
Then in every .md file, you add a frontmatter chunk that specifies the dependency graph. But you will notice, that since all files are equal citizens, we have unlocked context sharing. So your frontmatter for skill-1 and skill-2 might look something like this:
name: skill-1
type: SKILL # yes, there's a type, for the flat file purists
knowledge:
- knowledge-1
- org-context
agents:
- query-agent
scripts:
- script-1
name: skill-2
type: SKILL
knowledge:
- knowledge-2
- org-context
agents:
- query-agent
- agent-2
assets:
- asset-1
Both skills share org-context and query-agent without any need for rewriting. org-context may contain what the different teams in your org are, what they are working on, what common acronyms you use, what your product does, what systems each team uses, etc. That can all go in a single file that some group of people maintain. Then every single skill (and agent) pulls in your org-context file. Similarly, query-agent might mention common query patterns for objects you look up frequently. Again, your skills and agents can simply invoke it without needing to rewrite it. If something changes in your org, you update the associated knowledge file in one single place.
The powers of frontmatter, however, go beyond dependency trees. Frontmatter is multipurpose! It can be where you store file metadata. Like short description, skill trigger phrases, an mcp directory for the skill, and any other grouping mechanism you want. Here's a more realistic example of frontmatter for a skill that a game design lab may use:
---
name: encounter-tuner
type: SKILL
teams:
- design
- engineering
description: >
Tune a fight that feels wrong — quantify the difficulty, simulate candidate
changes, and hand back a tuning table, not an opinion.
knowledge:
- "[[encounter-tuning-model]]"
- "[[telemetry-schema]]"
agents:
- "[[quill-agent]]"
- "[[sim-agent]]"
mcp:
- quill-telemetry
triggers:
- "this boss feels too hard"
- "i need to tune this level"
- "the balance is off"
- "balance level"
---
Frontmatter replaces folders as the new organizing structure. And more powerful than folders because it can serve as a map for your agent about how to interpret the current file, where to look next, what context to pull, what tools it can access, etc.
These two simple changes - Flat Files and Frontmatter - give us lots of flexibility in how skills are built.
The Skill Viewer UI
So, considering this file system structure exists, how are people supposed to discover, read, and iterate on skills? Why, through the UI of course. Here's a sample webapp for the skillset of the fictional game design lab.
The feature set so far:
- File Navigator
- Clickable links to related files whenever they are mentioned
- Navigation shortcuts
- A Graph View (to show the interconnectedness of information)
- And more (see the sections below)
It is simple. It has moments of delight. It is interesting to explore the skills and see whats available to me, what each bit does, and how everything is related.
Down the line this could support some kind of skill contribution workflow too. I've played around with this but haven't found the right UX yet.
(Cross Platform) Skill Delivery
So far, we have written skills in a flat file structure and we have let people read them. But how do we deliver these skills so that agents can actually use them? Lets close the loop.
The Agent Skills standard expects a certain file structure, and harnesses that conform to that model will not perform the skill's instructions faithfully if they don't receive skills in the expected format.
There is always a little bit of skirmishing on the edge of any standard. Anthropic only reads skills from .claude/skills while everyone else reads skills from .agents/skills. And they all argue about what is 'allowed' to be in the frontmatter. Such a waste of potential. This bit cleans that up too.
So we add a compile step. The compiler takes our flat file structure, and...
- Strips out unexpected frontmatter
- Reads all the file relations we mentioned in our frontmatter and copies files to match Agent Skills (or really any distribution format)
- Builds our plugins for distribution (more details in the repo)
Thats it. Now your skills are flexible, sharable, and usable everywhere.
You can see more of the details of how I have implemented this in this sample repository. Visually in the app, you can see the different distributions like this:
Bonus: Skill Sets
Now lets extend the paradigm a little bit. Because of frontmatter, we now have easy skill categorization and grouping aka Skill Sets.
For example, maybe your engineering team has certain dev flow management skills, and your marketing team has campaign management skills. But also both teams share deck generation skills.
You can tag relevant teams on the frontmatter and extend the viewer to filter by team so that teams can explore skills relevant to them.
Then you could simply read this frontmatter tag at compile time and build different plugins for the teams to install...if you were so inclined.
You can group and filter skills by any factor named in your frontmatter. You can make your skills searchable. Maybe you add priority to your skills? Like try skills with P1 priority first, then if certain privileges are missing, go to skills with P2 priority, then to P3. Play around.
We can build a whole engine for our skills using frontmatter tags and hooks. More on hooks later, maybe.
Thats all for now. Reach out if you disagree, have an iteration, have a better approach, or related ideas you want to talk about.
AI Disclaimer
The fundamental concept of storing frontmatter flatly was something I came up with while reading Society of Mind by Marvin Minsky.
This article was completely handwritten. The viewer app was completely vibecoded