Agent Skills: How to Package Reusable Capabilities Without Overloading Context

An agent can be given a larger system prompt every time its responsibilities grow. That approach works until instructions become difficult to discover, maintain and test. Agent Skills provide a more modular option: package procedures, scripts and references as capabilities that can be loaded when relevant.

The open Agent Skills specification defines a skill as a directory containing a SKILL.md file with metadata and instructions. Optional folders can hold scripts, references and assets. Anthropic describes the pattern as progressive disclosure: the agent first sees compact metadata, loads the main instructions only when the task matches and opens supporting resources only when needed. OpenAI documents compatibility with the same open format for agent sandboxes and shell-based workflows.

What belongs in a skill

A useful skill contains procedural knowledge that should be reused: how to inspect a PDF, prepare a release checklist, run a particular analysis or produce a document in an approved format.

Include:

• a precise description of what triggers the skill;
• the ordered workflow and stop conditions;
• required inputs and expected outputs;
• examples of success and common failure;
• deterministic scripts for calculations or transformations;
• focused references that are loaded only when needed.

Do not use a skill as a dumping ground for every company policy. Global security and authority rules belong in the trusted harness or top-level instructions. Project facts belong in the appropriate source of truth.

Skills and tools are different

A tool exposes an action or data interface. A skill teaches the agent how and when to combine actions, sources and validation. A “create invoice” tool may accept structured fields. An accounts-payable skill may explain which records to verify, which tool to use, when approval is mandatory and how to document exceptions.

The skill can call tools, but it should not secretly broaden their permissions. The runtime remains responsible for authorization.

Design for progressive disclosure

Write metadata for discovery, not marketing. If the description is vague, the agent will miss the skill or activate it for unrelated tasks. Keep the main instructions small enough to understand as one procedure. Move detailed tables, templates and domain references into named files.

This reduces context pressure, but it also improves maintainability. A reviewer can inspect a bounded capability instead of searching one enormous prompt for relevant rules.

Security and supply-chain risk

A skill can contain executable code and instructions that influence tool use. Treat an untrusted skill like an unreviewed software dependency. Inspect scripts, network calls, bundled assets, installation steps and requested tools. Pin or record versions. Test inside a limited environment before promotion.

Evaluate the trigger and the result

Skill testing should answer two separate questions: Was the correct skill selected? Did it produce the intended result without harming unrelated behavior? Include positive tasks, near-miss tasks where the skill should not load and regression cases for existing workflows.

Use a skill when a procedure is repeated and benefits from versioned instructions or scripts. Do not create one for a single short prompt or a capability better enforced directly in code.

Continue with Context Engineering, AI Agent Tools and MCP and Continual Improvement.

Primary sources

• Agent Skills specification
• Anthropic: Equipping agents with Agent Skills
• OpenAI: Skills

Adaptation note: This article was informed by modular-capability concepts in AI Agents in Depth: Design Principles and Engineering Practice by Bojie Li and contributors, Apache License 2.0. Its structure and recommendations were independently developed from the cited specifications and engineering sources.