Agent Skills (or skills) are self-contained packages of instructions and resources that AI agents load on demand. Each skill is a version-controlled directory—alongside your code—centered on a SKILL.md file with YAML frontmatter (metadata) and a Markdown body (execution instructions) that tells the agent what to do and how to do it for a specific task. The agent reads the frontmatter to decide relevance and loads the full body only upon activation.
Why use skills?
Agents are capable but lack the procedural knowledge and organizational context needed for reliable real-world tasks. Skills package domain expertise into reusable files that extend agent capabilities without bloating every session. Key benefits:
-
On-demand loading: The agent loads a skill only when the task matches its description, keeping the context window focused.
-
Reusability: Write a skill once and reuse it across sessions, tasks, and team members.
-
Version control: Skills live in your code repository. Track changes with Git, review them in pull requests, and collaborate like you would with code.
-
Composability: The agent selects and combines multiple skills dynamically based on the task.
Skill structure
Each skill is organized as an independent directory following the Agent Skills specification:
my-skill/
├── SKILL.md # Required: metadata + execution instructions
├── scripts/ # Optional: executable code (Python, Bash, etc.)
├── references/ # Optional: detailed documentation, decision tables
└── assets/ # Optional: templates, schemas, data filesSKILL.md is the only required file. It has two parts: metadata and body.
-
Metadata: Requires at least
name(a unique identifier) anddescription(the applicable scenarios and trigger conditions). The agent decides whether to load a skill based on itsdescription. -
Body: Step-by-step operational procedure. May include conditional branches, checkpoints, and expected outputs, and must define clear success criteria.
How skills work
Skills use progressive disclosure to minimize context usage. The agent processes skills in three phases:
-
Discovery: At startup, the agent reads only the
nameanddescriptionfrom each skill's frontmatter (~100 tokens per skill) and evaluates relevance to the current task. -
Activation: When a task matches a skill's description, the agent reads the complete
SKILL.mdbody into its context (recommended <5,000 tokens). -
Execution: The agent follows the instructions in the body, loading files from
scripts/,references/, orassets/only as needed.
Skills provide procedural guidelines only. They do not override runtime or platform security policies. Operations such as configuration changes or production data access remain governed by the platform's identity, policies, and access controls.
Example: Query ECS instances
This example creates a skill that queries the running status of ECS instances.
Step 1: Create the skill directory
Create a skills/ecs-query directory with the following structure:
ecs-query/
├── SKILL.md # Metadata and execution instructions
├── references/
│ └── instance-status-codes.md # ECS instance status code reference
├── scripts/
│ ├── query-instances.py # Calls DescribeInstances to list instances
│ └── export-csv.py # Exports results as CSV
└── assets/
└── output-template.md # Output format templateCreate the SKILL.md file:
---
name: ecs-query
description: Query the running status of ECS instances. Use when the user wants to check, list, or view ECS instance status across regions.
---
# Query ECS instances
## Steps
1. Confirm the query scope: region and filter conditions (instance status, tags, etc.). Default to all regions if none specified.
2. Run `scripts/query-instances.py` with the specified region and filters to retrieve the instance list. Refer to `references/instance-status-codes.md` to interpret status codes.
3. Format the output using the template in `assets/output-template.md`:
- Query summary (region, total instance count)
- Instance table (name, ID, status, instance type, IP address)
4. If the user wants to export results, run `scripts/export-csv.py` to generate a CSV file.The SKILL.md consists of YAML frontmatter (name and description) and a Markdown body. Files in scripts/, references/, and assets/ use relative paths to separate execution logic from reference data.
Step 2: Import the skill
Place the skill directory in the path your agent platform expects:
|
Platform |
Skill path |
Discovery method |
|
Lingma |
|
Automatic directory scan |
|
Cursor |
|
Loaded via rules or agent configuration |
|
Claude Code |
|
Automatic directory scan |
For example, in Claude Code, move the ecs-query/ folder into .claude/skills/ to complete the import.
Step 3: Verify the skill
Enter a task that matches the skill's description. The agent automatically discovers and activates it.
For example, in Claude Code:
Check which ECS instances are running in the China (Hangzhou) region.The agent matches the ecs-query skill and returns the results in the format defined in the SKILL.md:
ECS Instance Query Results
Query summary:
- Region: China (Hangzhou)
- Running instances: 3
Instance list:
| Instance name | Instance ID | Status | Instance type | IP address |
|---------------|----------------------|---------|-----------------|----------------|
| web-server-01 | i-bp1a2b3c4d5e6f7g8h | Running | ecs.g7.xlarge | 172.16.0.10 |
| api-gateway | i-bp2c3d4e5f6g7h8i9j | Running | ecs.c7.large | 172.16.0.20 |
| db-backup | i-bp3d4e5f6g7h8i9j0k | Running | ecs.r7.2xlarge | 172.16.0.30 |Skill file formats, content structure, and security policies may vary between platforms. Check your platform's documentation for details.