Understanding Agent Skills - The Building Blocks of Autonomy

An LLM is a reasoning engine. It thinks, it plans, it decides.

But it can't do anything on its own.

Skills are how you give it hands.

Tools vs. Skills

A readFile tool and a writeFile tool seem like enough. Read a file, decide what to change, write the result.

Except the agent writes to the wrong path. Overwrites files it shouldn't touch. Produces files with syntax errors.

The tools work perfectly. The skill is broken.

What's the difference?

A tool is just execution. A skill includes the reasoning about when to use it, the validation of whether it worked, and the recovery plan for when it doesn't.

Three Types

Every agent skill falls into one of three categories. Recognizing which one you're building changes how you design it.

Primitive Skills

Raw capabilities. readFile, searchWeb, runCommand, callAPI. One thing, done directly, result returned.

The key principle: primitives should be stateless and idempotent whenever possible.

If readFile is called twice with the same path, it should return the same content. If runCommand runs mkdir -p, it shouldn't fail if the directory exists.

Why does this matter?

Agents will call your primitives multiple times. They retry. They backtrack. If your primitives have side effects that compound on repeated calls, you'll have bugs that are nearly impossible to trace.

Composite Skills

This is where it gets interesting.

A composite skill chains multiple primitives into a higher-level capability. "Research this topic" might involve searchWeb → readUrl → summarize → storeResult. "Debug this error" might involve readFile → analyzeError → editFile → runTests → verifyFix.

The tricky part is error propagation. If step 3 of a 7-step composite skill fails, what happens?

Retry the step? Skip it? Roll back everything?

There's no universal answer. It depends on the skill. But you must decide explicitly. The worst thing is leaving it to the agent to figure out on the fly.

Interactive Skills

Skills that involve communication — with humans, with other agents, with external systems that require back-and-forth.

askClarification. requestApproval. negotiateHandoff.

These are the hardest because they break the synchronous execution model. The agent sends a message, then waits. While waiting, it needs to maintain its state so it knows what to do when the response arrives.

The cleanest pattern is to treat interactive skills as state machine transitions:

The Discovery Problem

When you have 5 skills, you list them all in the system prompt.

When you have 50, you can't.

The context window fills up with tool descriptions and the agent starts hallucinating tools that don't exist.

The fix: give the agent a catalog skill that searches for other skills by description. The agent says "I need something that talks to Kubernetes," the catalog returns the relevant skill definitions, the agent loads only what it needs.

Dependency injection for AI.

interface SkillCatalog {
  search(query: string): Promise<SkillDefinition[]>;
  load(skillId: string): Promise<LoadedSkill>;
  unload(skillId: string): Promise<void>;
}

interface SkillDefinition {
  id: string;
  name: string;
  description: string;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
  requiredPermissions: string[];
}

This scales. A hundred skills, and the agent consistently finds and uses the right ones without polluting its context with irrelevant definitions.

The Right Level of Abstraction

Early on, the temptation is to make skills too granular. Separate skills for createDirectory, checkDirectoryExists, listDirectory, deleteDirectory. The agent spends more time orchestrating filesystem operations than doing actual work.

Better: compose these into ensureDirectoryStructure and cleanupWorkspace. Fewer choices, less confusion, better results.

The right abstraction for a skill is: one intent, fully realized.

Not "create a file" but "ensure this file exists with this content and verify it."

A skill has a clear purpose. When that purpose is met, the skill is done.