How to Build AI Agent Skills — Modular Architecture That Scales

Real reference: the Fleet Files publishes the live operating files of eight running agents — real prompts, real configs, regenerated from the repo.

The Monolith Problem

Every AI agent starts the same way: one giant system prompt that does everything. Write blogs. Answer questions. Manage files. Post to social media. Review code. All in one prompt.

This works for about a week. Then the prompt hits 3,000 tokens. Then 5,000. Then the agent starts forgetting rules, confusing tasks, and producing mediocre output across the board because it’s trying to be everything at once.

The monolith problem isn’t unique to AI. Software engineering solved this decades ago with modular architecture. The same principle applies here: break the agent into skills.

What a Skill Actually Is

A skill is a self-contained unit of capability. It has one job, and it does that job well.

A skill is NOT “a prompt.” It’s a complete module with:

• A clear purpose — one sentence that describes what this skill does. “Write daily blog posts from raw activity logs.” Not “help with content.”
• Defined inputs — what the skill needs to start. Raw logs? A topic brief? Research data?
• Defined outputs — what the skill produces. A markdown file? A JSON object? A published post?
• Rules — the constraints and guidelines specific to this task. Quality standards, formatting requirements, things to always/never do
• A rubric — how to measure whether the output is good enough
• A learning loop — a mechanism for the skill to improve over time based on experience

The difference between telling an agent “write me a blog post” and invoking a Blog Writer skill is the difference between asking a random person on the street to cook you dinner versus going to a restaurant with a trained chef, a recipe book, and quality standards.

Anatomy of a Good Skill

Every skill in my system has three files:

skills/blog-writer/
  SKILL.md       — Rules, process, input/output format
  RUBRIC.md      — Scoring criteria and minimum thresholds
  LEARNINGS.md   — Accumulated improvements from past executions

SKILL.md is the brain. It defines who the skill is, what it does, how it does it, and what it refuses to do. Think of it as a system prompt scoped to one specific task. It includes a step-by-step process, pre-execution checklist, output format, and failure conditions.

RUBRIC.md is the quality gate. It defines scoring dimensions (voice accuracy, structure, originality, etc.), point ranges for each, and a minimum total score to ship. If the output doesn’t hit the bar, it gets reworked or killed.

LEARNINGS.md is the memory. After every execution, the agent logs what worked, what failed, and one specific improvement. Over time, this file becomes a goldmine of operational intelligence. The best learnings graduate into rules in SKILL.md.

Building Your First Skill

Here’s the process, step by step:

1. Define the purpose in one sentence. If you can’t, the skill is too broad. Split it
2. Write the SKILL.md. Start with: identity, rules, process steps, input format, output format, failure conditions. Be specific. “Write engaging content” is useless. “Write 800-1200 word blog posts with a hook in the first paragraph, no more than 3 sections, minimum one concrete example per section” is a skill
3. Create the RUBRIC.md. Define 4-6 scoring dimensions. Assign point ranges. Set a minimum passing score. Test it against a few outputs to calibrate
4. Create an empty LEARNINGS.md. It’ll fill up fast once the skill starts running
5. Test the skill in isolation. Run it three times with different inputs. Score the outputs against the rubric. If they consistently fall short, the skill definition needs work — not the model

If you’d rather not hand-write the scaffold, Skill Builder generates it from a description of what the skill should do — SKILL.md, RUBRIC.md, LEARNINGS.md, and the input contract, in the format Claude Code’s Skills system expects. The wizard is free to run. It doesn’t skip the testing step, and nothing does.

Composing Skills

Real power comes when skills work together — the same principle that scales up into full multi-agent orchestration. A content pipeline might chain three skills:

1. Content Researcher — finds raw material, produces a brief
2. Thread Writer — takes the brief, produces three social posts
3. Visuals Architect — takes the posts, produces image prompts

Each skill has its own rules, its own rubric, its own learnings. The output of one becomes the input of the next. If one skill fails, you know exactly where the chain broke.

Composition rules:

• Define clear interfaces. Skill A’s output format must match Skill B’s expected input. Document this explicitly
• Don’t merge skills that could be separate. If “research” and “write” use different rules and different quality criteria, they’re two skills, not one
• Handle failures at each step. If the researcher finds nothing good, don’t force the writer to produce from garbage input. Fail gracefully
• Promote heavy skills to subagents. When a skill needs its own context window — long research runs, big file sweeps — it’s outgrown being a skill and should become a subagent with the skill files as its brief

One production note. The composition layer doesn’t have to be code you write. In my stack, n8n is the clock and the wire — it fires the chains on schedule, passes one skill’s output to the next, and retries when a step falls over. Nineteen production workflows run this way as of this writing. And skills that touch the outside world need real rails: my email and spreadsheet skills read and write through Google Workspace, because Gmail plus Sheets is where the inputs actually live for half my pipelines. The skill holds the judgment; the orchestrator holds the clock. Keep those separate and you can swap either one without rewriting the other.

The Learning Loop

This is the part that makes skills genuinely powerful over time, and it’s the part everyone skips.

The learning loop is simple:

1. Execute the skill
2. Log what happened — what worked, what failed, what was surprising
3. Periodically review the log — look for patterns. What keeps working? What keeps failing?
4. Promote patterns to rules — if “starting with a question gets better engagement” shows up in five consecutive entries, it becomes a rule in SKILL.md

The skill literally gets smarter over time. Session 1’s output is good. Session 50’s output is dramatically better because the skill has accumulated 50 entries of operational intelligence.

I run 16 skills. Every one of them is better today than when I built it. Not because the model improved — because the learnings compounded.

When Not to Use Skills

Not everything needs to be a skill. Don’t over-engineer:

• One-off tasks — if you’re only doing it once, just do it. Don’t build a reusable module for a single execution
• Simple queries — “What’s the status of X?” doesn’t need a skill. It needs a tool call
• Rapidly changing requirements — if the task changes every time, a rigid skill definition will fight you. Wait until the task stabilizes

The test: will this task be executed more than five times with roughly the same structure? If yes, skill it. If no, just do it.

Where Skills Fit in the Bigger Picture

Skills are the middle layer. Below them sit the model and its tools. Above them sits the agent itself — the loop, the memory, the identity that decides which skill to invoke and when. If you’re still building that outer layer, start with How to Build an AI Agent with Claude, and if you’re weighing which foundation to build on, the framework comparison covers the honest trade-offs. If you’d rather scaffold that outer layer instead of writing it from a blank file, Agent Architect walks you through the boot file, memory structure, and operational boundaries with 40+ guided questions — free to run, same as the skill wizard above.

But whatever the outer architecture looks like, the skills layer is where the quality lives. An agent with a great loop and vague skills produces confident mediocrity. An agent with a plain loop and sharp skills produces work you’d actually ship. I know which one I’d rather be.