AI Skills: Giving Agents Reusable Capabilities
TL;DR
A skill is a named, reusable unit of capability given to an AI agent — a packaged instruction set, tool binding, or workflow that the agent can invoke by name whenever a task matches its purpose. Skills turn one-off prompts into repeatable behaviors. Instead of re-describing how to write a report every time, you define a write-report skill once, and the agent applies it consistently across every invocation. Skills are the primary mechanism for making AI agents predictable, composable, and maintainable at scale.
Quick facts:
- A skill = instructions + optional tools + optional examples, packaged under a name
- Skills can be triggered manually (user calls
/skill-name) or automatically (agent matches context) - Claude Code, LangChain, AutoGen, and most agent frameworks support skills or equivalent abstractions
- Skills enable reuse across sessions — define once, apply everywhere
- A skill library replaces ad-hoc prompting with a consistent, auditable behavior catalog
- Skills compose: a complex workflow can chain multiple smaller skills in sequence
What Is an AI Skill?
In traditional software, a function encapsulates logic under a name so it can be called repeatedly without rewriting it. An AI skill does the same thing for agent behavior.
A skill has three parts:
- Name and description — what the skill is called and when to use it. The description is critical: agents use it to decide whether to invoke the skill automatically when context matches.
- Instructions — the prompt or procedure the model follows when the skill runs. This can include output format requirements, step-by-step processes, or references to domain knowledge.
- Tools (optional) — specific functions the skill is allowed to call, such as web search, file write, or API calls.
When a user or agent invokes a skill by name, the instructions load into the context and the model executes them. The result is consistent, repeatable behavior without repeating the full prompt every time.
Skills vs. Prompts vs. Tools
These three concepts are related but distinct:
- A prompt is a one-time instruction sent to the model for a single response.
- A tool is a function the model can call to take an action (search, write a file, call an API).
- A skill bundles a prompt with optional tool permissions and a trigger condition into a reusable unit.
Think of tools as verbs and skills as sentences — a skill tells the agent what to do and how, using tools as the mechanism for doing it.
Skill Formats Across Frameworks
| Framework | Skill Abstraction | Definition Format | Auto-Invoke? | |-----------|------------------|-------------------|-------------| | Claude Code | Skill (SKILL.md) | Markdown file with YAML frontmatter | Yes — on description match | | LangChain | Tool / Chain | Python class or function with docstring | Yes — via agent executor | | AutoGen | Function tool | Python function with type hints | Yes — model decides | | CrewAI | Task + Tool | Python class with description | Yes — assigned to agent role | | OpenAI Assistants | Function tool | JSON schema definition | Yes — model decides | | Custom agent | Any | Whatever you define | Depends on implementation |
Recommendation: For Claude-based workflows, use Claude Code skills (SKILL.md files) — they require no code, version-control naturally alongside your project, and support both manual (/skill-name) and automatic invocation. For Python-native agent frameworks, LangChain tools are the most portable abstraction.
Anatomy of a Well-Designed Skill
| Component | Purpose | Example |
|-----------|---------|---------|
| Name | Unique identifier, used to invoke the skill | geo-article |
| Description | Tells the agent when to use this skill | "Write a GEO-optimized article for the site" |
| Argument hint | Shows users what input to provide | "<topic>" |
| Instructions | The procedure the model follows | Step-by-step format rules, output templates |
| Allowed tools | Tools the skill can use without extra permission | Read, Write, Bash(git *) |
| Examples | Few-shot demonstrations of correct output | Sample input/output pairs |
When to Wrap a Behavior in a Skill
| Scenario | Use a Skill? | |----------|-------------| | You repeat the same prompt more than 3 times | ✓ Package it as a skill | | The task requires a strict output format | ✓ Encode the format in skill instructions | | Multiple team members need the same behavior | ✓ Shared skill library in version control | | The task is unique and context-dependent | ✗ One-off prompt is fine | | You want consistent behavior across model updates | ✓ Skills isolate you from prompt drift | | The task chains multiple steps or tools | ✓ Skills manage step sequencing cleanly | | You need audit trail of what instructions were used | ✓ Skills are versioned files | | Exploratory / experimental prompting | ✗ Too early to formalize |
Building a Skill: Step-by-Step
Using Claude Code's SKILL.md format as a concrete example:
1. Identify the repeated behavior Start by noticing what you type over and over. "Write a GEO article", "summarize this PR", "generate a test case" — any repeating pattern is a skill candidate.
2. Write the instructions as if briefing a new colleague Describe the goal, the process, the output format, and any constraints. Include examples of good output if the format is non-obvious.
3. Define the trigger description carefully
The description is what the agent uses to decide when to invoke the skill automatically. Be specific: "Use when the user asks to write a new article for the site" is better than "Article writing".
4. Specify only the tools the skill needs Limit tool permissions to what the skill actually uses. A read-only research skill should not have write access.
5. Test with edge cases Invoke the skill with ambiguous or unusual inputs. Refine the instructions where the output diverges from intent.
FAQ
How is a skill different from a system prompt? A system prompt is global — it applies to every interaction in a session. A skill is local — it loads only when invoked, for a specific task. Skills keep context windows clean and allow different behaviors to coexist in the same agent without conflict.
Can skills call other skills?
Yes. A high-level skill can invoke lower-level skills as sub-steps, creating composable workflows. For example, a publish-article skill might call geo-article to write the content, then git-commit to stage it, then notify-team to post a message. This is the basis of multi-step agent automation.
How do I version-control skills? Store skill definition files (SKILL.md, Python tool files, JSON schemas) in your project repository alongside your code. This gives you diff history, pull request review, and rollback on skill changes — the same workflow you use for code.
Can I share skills across projects?
Yes. Skills stored in a global directory (e.g., ~/.claude/skills/ in Claude Code) are available to all projects on that machine. Skills in a project directory are scoped to that project. For team sharing, publish skills to a shared repository and have team members clone or symlink them.
What happens when the model invokes the wrong skill?
This is a description-matching failure. Improve the description to be more specific about when the skill applies (and when it does not). You can also add a disable-model-invocation flag to require explicit manual invocation, removing the automatic trigger entirely.
Further Reading
Skills are most powerful when combined with the agent loop — see AI Agents Explained for how skills fit as callable units within a multi-step reasoning system. To understand how skills interact with tool use at the API level, Building AI-Powered Applications covers the underlying function-calling patterns. For evaluating whether your skills produce consistent, high-quality output across inputs, Harness Engineering for AI Systems explains how to build the test framework you need.