Agent Skills

Most teams using AI agents are stuck in the "everyone prompts differently" phase. One developer writes detailed system prompts, another copies examples from Twitter, a third types stream-of-consciousness requests. The outputs are inconsistent, the knowledge is trapped in individual conversations, and there's no way to improve systematically.

Skills solve this. A skill is a reusable markdown document that encodes domain knowledge, process steps, reference materials, and output expectations. Instead of prompting from scratch every time, the agent loads the relevant skill and follows a tested, version-controlled process.

What a skill is (and isn't)

A skill is durable knowledge used frequently but updated relatively rarely. It's the agent equivalent of a playbook or standard operating procedure.

A skill is not:

• A one-off prompt (use a prompt for that)
• Dynamic data that changes constantly (use a tool/API for that)
• A conversation transcript (use a session log for that)

The distinction matters because skills live in version control, get reviewed in PRs, and improve over time. One-off prompts live in chat history and get lost.

Anatomy of a good skill

A well-structured skill has:

Identity - what it's for, when to use it, what it produces. This is the trigger: the agent (or human) reads the description and decides whether this skill fits the current task.

Process - numbered steps that walk through the work. Each step should be specific enough that the agent produces consistent output regardless of who invoked it or when.

Knowledge context - pointers to reference documents the agent should read before executing. This is how you manage context scope: the skill tells the agent exactly what information it needs, no more and no less.

Output format - explicit rules for what the skill produces. Templates, structure, voice guidelines, required sections. The more specific the format, the more consistent the output.

Skills and context discipline

Context discipline - giving agents the right information at the right time - is one of the hardest problems in AI product development. Skills are the primary mechanism for solving it.

Without skills, context management is ad hoc. Users dump everything into the prompt and hope the model figures out what matters. With skills, context is scoped: the skill specifies which documents to read, which tools to use, and what information to gather from the user.

This directly impacts the Context Discipline dimension of the AI Health Indicator. Teams with well-structured skill libraries consistently score higher because their agents operate with right-sized context instead of everything-at-once.

Building a skill library

Start with repetition

Look for tasks your team does repeatedly with AI: code reviews, status updates, document generation, data analysis, onboarding materials. If someone is writing a similar prompt more than twice a week, it should be a skill.

Version control from day one

Skills are code. Store them in your repo, review changes in PRs, track who changed what and why. This gives you auditability, rollback capability, and the ability to improve systematically.

Let agents help build skills

The fastest path to a good skill is to do the task once with an AI agent, capture what worked, and encode it. Let the agent generate the first draft of the skill document, then refine it through use.

Continuous improvement

Track which skills get used, which produce good outputs, and which get overridden or abandoned. The improvement loop: use the skill → evaluate the output → update the skill → repeat. Over time, your skill library becomes your team's institutional knowledge about how to use AI effectively.

The maturity progression

Level	What it looks like
Ad hoc	Everyone prompts differently. No shared knowledge.
Collected	Team has a shared folder of "good prompts." No structure or versioning.
Structured	Skills follow a standard format, live in version control, get reviewed.
Systematic	Skills are triggered automatically, improved continuously, and measured for effectiveness.
Institutional	The skill library is the team's operating system for AI-assisted work. New team members onboard by reading skills.

Most teams are between Ad hoc and Collected. The jump to Structured is where the real value appears - that's when consistency, reliability, and improvability kick in. This progression maps to the broader AI maturity framework.