How to Structure a Library of AI Agent Skills

Organize skills by business function, not by tool, keep every skill scoped to exactly one job, write frontmatter an agent can match against real requests, and version the whole library in git. That's the structure that scales past ten skills — everything else is a folder of prompts waiting to become archaeology.

Anyone can write one good skill. The library is the hard part. FAST's library holds 300+ skills that stay findable, non-overlapping, and consistently structured — and the reason isn't discipline. It's five structural decisions, made once. If you're new to what a skill even is, start with the SKILL.md pattern explained, then come back.

Step 1: Pick a taxonomy from the business, not the tech

The instinct is to organize skills by tool ("Notion skills," "Stripe skills") or by model. Both rot instantly — tools change, and no founder thinks "I have a Stripe problem." They think "I have a pricing problem."

FAST organizes by the OSLO taxonomy: four categories that cover every function of a business.

The property that matters: every task maps to exactly one category. No ambiguity about where a skill lives, no judgment calls about where to look. Your taxonomy doesn't have to be OSLO — but it has to have that property, and it has to come from how the business works rather than which vendors it currently uses.

Step 2: One skill, one job

The most common library-killer is the mega-skill: "marketing.md," three thousand lines, covering everything and triggering on anything. Agents select skills by matching the request against each skill's name and description — a skill that claims everything matches everything, and selection accuracy collapses.

Scope each skill to one coherent job: write a sales page, build a lead magnet, process a meeting transcript. The test: can you state when the skill should trigger in one sentence without the word "and" doing heavy lifting? When a skill outgrows one job, split it. Narrow skills are easier for agents to pick correctly, easier for you to improve, and safer to hand to a new team member.

Step 3: Write frontmatter like it's the interface — because it is

Agents don't read your whole library on every task; that would drown the context window. They skim each skill's YAML frontmatter — name plus description — pick the match, and load the full file only when needed. Which means the description is not documentation. It's the routing layer.

Write descriptions that contain the actual phrases a user would say: not "email marketing utilities" but "use when creating drip sequences, broadcast campaigns, or subscribe endpoints — triggers on 'email campaign,' 'drip,' 'automation.'" Include trigger words. Include what the skill does not cover if a sibling skill handles it. Every mis-triggered skill traces back to lazy frontmatter.

Step 4: Standardize the internal anatomy

When every skill has the same skeleton, agents extract what they need faster and humans audit quality at a glance. FAST skills use YAML frontmatter plus 19 required sections — quick start, core frameworks, tiered tactics, templates, and a quality checklist — with the checklist as the non-negotiable: it's the pass/fail criteria the agent runs before calling the job done, and it's what keeps probabilistic output inside acceptable variance.

A skill without a quality checklist is a suggestion. A skill with one is a standard.

Step 5: Version it in git and make it self-expanding

Skills are text files. That means they diff, branch, blame, and roll back like code — so treat them like code. A git repo gives you history when an edit quietly degrades output, an audit trail of who changed what, and free distribution: pull the repo and every machine, every agent, has the current library. It also keeps the library yours — portable across agents and platforms, which is the whole point of the factory model.

Then close the loop with a meta-skill: a skill whose job is creating new skills to the house standard — correct frontmatter, all required sections, checklist included. The workflow becomes: do a job manually once, capture the process, invoke the meta-skill, commit. The library grows as a byproduct of doing the work. That's how FAST added new skills every week without the standard slipping.

What are the failure modes to avoid?

• Duplicate skills. Two skills covering the same job with different advice — the agent picks one at random and you get inconsistent output. Merge or delete; the taxonomy exists to make duplicates visible.
• Stale skills. A skill that references a dead process is worse than no skill — the agent follows it confidently. When you correct an agent's output, update the skill, not just the instance.
• Knowledge that should be a tool. If a "skill" is really a sequence of exact API calls, make it a deterministic tool instead — see how to give agents tools safely. Skills are for judgment; tools are for execution.

FAQ

How should I organize my AI agent skills?

Organize by business function, not by tool or model. The FAST framework uses the OSLO taxonomy — Offers, Sales, Leads, Operations — so every task maps to exactly one category. Keep each skill scoped to one job, give it trigger-rich frontmatter so agents can find it, and version the whole library in git.

How many skills should one skill file cover?

One job per skill. A skill that tries to cover "all of marketing" triggers on everything and executes nothing well. When a skill grows past a single coherent job, split it — narrow skills are easier for agents to select correctly and easier for you to improve.

Should skills live in git?

Yes. Skills are text files, which means they diff, branch, and roll back like code. Git gives you history when an edit degrades output quality, an audit trail of what changed, and a distribution mechanism — pull the repo and every machine has the current library.

What is a meta-skill?

A meta-skill is a skill whose job is creating new skills to a consistent standard — correct YAML frontmatter, all required sections, templates, and a quality checklist. It makes the library self-expanding: capture any process once and the meta-skill packages it properly.