The AI software development lifecycle (AI SDLC) extends familiar software engineering practices to systems that use models and agents. Alongside requirements, design, implementation, testing, deployment, and monitoring, teams must manage prompts, tool access, context, evaluation, and human oversight. Agent skills fit into this lifecycle as reusable units of task knowledge. Instead of repeating the same code-review checklist in every prompt, a team can store it once and let a compatible agent load it when reviewing code: define the recurring task and its expected outcome, design concise instructions with boundaries and examples, build in supporting scripts or reference material only when useful, evaluate triggering, correctness, edge cases, and token use, and maintain the skill by versioning it, reviewing changes, and retiring obsolete guidance.
1. Introduction to agent skills
An agent skill is a packaged set of instructions and optional resources that helps an AI agent perform a particular kind of task. For example, a skill might explain how to review a pull request, summarize an incident, write release notes, or analyze a dataset. A skill is not necessarily a model, an agent, or an external tool. It primarily supplies task-specific know-how. The agent still uses its model and whatever tools its runtime permits. Skills are useful when a task is repeated, requires a consistent process, or needs more detailed guidance than should live in the always-on system prompt. They are less useful for one-off tasks that need only a short instruction.
1.1 Why your giant system prompt stops working
A large system prompt often starts as a practical shortcut: add every team convention, workflow, exception, and example in one place. As the system grows, this approach becomes harder to maintain.
- Context competition: persistent instructions consume tokens that could otherwise be used for the user’s task, relevant files, and tool results.
- Lower signal-to-noise ratio: instructions for unrelated tasks sit beside the instructions that matter now.
- Conflicting guidance: duplicated rules can drift apart and give the model inconsistent signals.
- Harder maintenance: a small change to one workflow can require reviewing a large prompt.
- Weak modularity: teams cannot easily reuse, test, or version one capability independently.
The solution is not to remove all important context. Keep stable, global behavior in the system prompt, and move detailed task procedures into skills that are loaded when relevant. This reduces unnecessary context while preserving access to the instructions when they are needed.
1.2 Token optimization for agent skills
Token optimization means placing the right information in the right layer, not simply making every file as short as possible.
| Layer | What belongs there | Example |
|---|---|---|
| Always-on prompt | Stable identity, global constraints, and high-priority behavior | Never expose secrets; ask before destructive actions. |
| Skill summary/metadata | Short description that helps the agent decide whether a skill applies | Use for reviewing code changes for correctness and security. |
| Skill instructions | Detailed workflow, checklist, expected output, and exceptions | Inspect changed files, assess impact, and report actionable findings. |
| References or scripts | Long documentation or deterministic work that need not be in every prompt | Team-specific API rules or a lint script. |
Practical ways to optimize:
- Remove duplicated instructions and examples that do not change behavior.
- Use specific skill descriptions so the runtime can select the right skill.
- Load detailed references only when required, if the agent platform supports on-demand loading.
- Prefer scripts for deterministic transformations or checks where code is more reliable than prose.
- Measure token usage and task quality together. A shorter prompt that causes more mistakes is not an optimization.
Important: progressive loading is a capability of the agent runtime, not a guarantee of every skill format. A folder containing instructions saves context only if the runtime avoids loading all of it for every task.
1.3 Anatomy of a skill
A common skill layout has a directory with a required instruction file and optional supporting resources. Exact naming and metadata requirements depend on the agent platform.
code-review/
├── SKILL.md # purpose, instructions, workflow
├── references/
│ └── review-guide.md
└── scripts/
└── check-diff.sh
SKILL.md is the only required file — the runtime reads it to decide relevance and to load the workflow; references/ and scripts/ are optional, loaded only if the instructions in SKILL.md point to them, which is why they stay out of the main file and don’t cost context on every task.
A typical SKILL.md contains:
- Metadata: a name and short description that explain when the skill applies.
- Purpose: the task and intended result.
- Workflow: the steps the agent should follow.
- Constraints: boundaries, safety checks, and things not to assume.
- Output format: how to present the result consistently.
- Optional resources: references, templates, or scripts for details and repeatable operations.
Keep the main instruction file focused. Supporting files should exist because they add useful detail or executable behavior—not merely to make the folder look sophisticated.
1.4 Where skills live and how agents find them
Skills commonly live in a project repository or in a user-level directory managed by an agent application. The exact path, discovery rules, and precedence vary by platform, so always check the runtime’s documentation.
- Project-level: stored with the codebase so the team can review and version them together.
- User-level: available across projects for an individual developer, where supported.
- Organization-managed: distributed through a centrally managed configuration or platform, where supported.
A typical discovery flow looks like this:
- The runtime scans supported skill locations or receives a configured skill catalog.
- It reads skill metadata, such as the name and description.
- It matches the task to the available descriptions and selection rules.
- When a skill is relevant, the runtime loads its detailed instructions and any needed resources.
- The agent follows those instructions within its normal permission and tool boundaries.
For example, a request to review a pull request may activate a code-review skill, while a request to draft a release announcement may activate a release-notes skill. Do not assume every agent discovers or activates skills identically.
1.5 Skills vs. rules vs. MCP vs. hooks vs. plugins
These concepts solve different problems and can work together.
| Concept | Main purpose | Example |
|---|---|---|
| Skills | Package task-specific knowledge and workflows | How to review a pull request. |
| Rules | Set persistent constraints or conventions | Follow repository formatting and never log secrets. |
| MCP | Standardize how compatible clients connect to external tools and context providers | Retrieve an issue or read a document from a connected service. |
| Hooks | Run code at defined lifecycle events in a supporting environment | Run a formatter after a file edit or validate a command. |
| Plugins | Add application-specific capabilities or integrations | A platform extension that provides a specialized action. |
A simple way to remember the difference: skills explain how to do a task; rules define constraints; MCP exposes tools or context; hooks automate lifecycle events; plugins extend a host application. Their exact behavior depends on the products and runtimes being used.
2. Example: build a code-review skill
Suppose a team wants an AI agent to review code changes consistently. Rather than repeating a long review prompt, create a small skill with a clear trigger, a workflow, and a predictable output.
2.1 Create the folder
Start with the smallest possible layout — one skill folder with a single instruction file, nothing else yet:
skills/
└── code-review/
└── SKILL.md
The folder name (code-review) and the file name (SKILL.md) are what a compatible runtime scans for when building its skill catalog — nothing inside the file matters yet at this point, only that the file exists at this expected path so the runtime knows to read it next.
2.2 Add the skill instructions
Fill SKILL.md with the metadata the runtime uses to decide relevance, followed by the workflow and output format the agent should actually follow:
--- name: code-review description: Review code changes for correctness, security, reliability, and maintainability. Use when asked to review a diff, pull request, or proposed code change. --- # Code Review Review the supplied diff and relevant surrounding code. ## Workflow 1. Identify what changed and the intended behavior. 2. Look for concrete bugs, security risks, data-loss risks, and backward-compatibility issues. 3. Trace important assumptions into nearby callers or tests when that context is available. 4. Report only actionable findings supported by evidence. 5. Do not claim that tests passed unless they were run. ## Output For each finding, include: - Severity: high, medium, or low - Location: file and line when available - Problem: what can go wrong - Recommendation: a concise fix If no actionable issue is found, state that clearly and mention any relevant testing limitations.
The name/description frontmatter is the only part a runtime typically reads before deciding this skill applies, which is why the description names the trigger (“diff, pull request, or proposed code change”) explicitly rather than just the topic; the Workflow section is the step-by-step procedure loaded once the skill is actually selected; and the Output section fixes the response shape so every review — across different diffs and different runs — reports the same four fields instead of free-form prose.
2.3 Ask the agent to review a change
In an agent runtime that supports this skill format and location, provide a task such as:
Review the current diff for correctness and security. Use the code-review skill if it applies.
The runtime can use the skill description to decide whether it is relevant, then load the detailed workflow. The agent inspects the diff and surrounding code available to it, and returns findings in the requested format. The exact activation behavior depends on the runtime.
2.4 Code output
Running the task from 2.3 against the sample diff produces one finding in exactly the four-field shape the Output section required:
Finding 1 Severity: high Location: src/payment.ts:42 Problem: The payment retry path can submit the same transaction more than once when the first response times out. Recommendation: Use an idempotency key and verify the provider's transaction status before retrying. Testing limitations: The diff was reviewed, but the test suite was not run.
Each labeled line maps directly back to the SKILL.md workflow: Severity/Location/Problem/Recommendation are the four required output fields in order, and the trailing Testing limitations note exists because step 5 of the workflow explicitly forbids claiming tests passed unless they were actually run — the agent is disclosing that it only read the diff, not that it verified the fix.
3. Conclusion
Agent skills are a practical way to make recurring AI workflows reusable and easier to maintain. They help separate global instructions from task-specific knowledge, and—when the runtime supports on-demand loading—can reduce unnecessary context. Start with one recurring task, write a focused skill, define a useful output format, and test it against real examples. Keep the system prompt for global behavior, use rules for persistent constraints, MCP for external tools and context, hooks for lifecycle automation, and plugins for host-specific extensions. Add complexity only when testing demonstrates a need.
