Agent Skills (Skills for short) is a collection of instructions and materials loaded by the intelligent body on demand, organized and versioned in the form of a separate directory. At the heart of each Skill is a SKILL.md file that contains metadata and execution instructions from which the smart body determines when to load and how to execute it.
Why do you need skills?
Skills encapsulate domain processes, tool usage, and organizational constraints as a collection of reusable files. Once created, you can use it repeatedly in multiple sessions and tasks to ensure execution consistency. Skills have the following core characteristics:
On-demand loading: The smart body loads the corresponding Skill only when the task matches, avoiding irrelevant instructions from occupying the context window.
Reusable: The same skill can be used repeatedly in different sessions and tasks. You do not need to write instructions repeatedly.
Versionable: The file is stored in the code repository. You can manage Git versions, review code, and collaborate with the team.
Combinable: Multiple Skill can work together, and the agent can be dynamically scheduled and combined according to the needs of the task.
Structure of Skill
Each skill is organized as an independent directory. The directory follows the Agent Skills specification and uses the following structure:
my-skill/
├── SKILL.md # Required: the main file, which contains metadata and execution instructions.
├── references/ # Optional: in-depth reference materials, field descriptions, and decision tables
├── tools/ # Optional: auxiliary scripts and code snippets
└ ── assets/ # Optional: static resources The SKILL.md is the only required file and consists of two parts: metadata and body:
Metadata: At least
name(unique identifier) anddescription(applicable scenario and trigger condition). The smart body determines whether to load the Skill based on thedescription.Text: describes the operation process step by step, including conditional branches, checkpoints, and expected output, and defines clear success criteria.
How Skills Works
Skills uses a progressive disclosure mechanism. Instead of loading the full content of all Skill at once, the smart body loads on demand in stages, controlling context occupancy:
Discovery: When the smart body starts a task, only the name (
name) and description (description) in each Skill metadata are loaded to determine its relevance to the current task.Activation: When a task matches the description of a Skill, the agent reads the complete
SKILL.mdfile of the Skill into the context.Execute: Execute the operation according to the instructions in the
SKILL.mdand load the referenced reference file or execute the attached script as needed.
Skill only provides operation guidelines and cannot replace the run time environment and policy. Whether operations such as configuration changes or access to production data are allowed is still determined by the identity, policies, and processes of the platform.
Example
For example, to query the status of an ECS instance, create a Skill that contains the complete directory structure and verify the effect.
Step 1: Create the Skill directory
Create a new skills/ecs-query folder under the project directory and organize the files according to the following structure:
ecs-query/
├── SKILL.md # Main file: metadata and execution instructions
├── references/
│ └ ── instance-status-codes.md# ECS instance status code and meaning comparison table
├── tools/
│ ├── query-instances.py # Call the DescribeInstances interface to query the instance list
│ └ ── export-csv.py # Export the query results as a CSV file
└── assets/
└ ── output-template.md # The output format template Create the SKILL.md file:
---
name: ecs-query
description: When you need to view the running status of an ECS instance, you can call the DescribeInstances operation to query and summarize the output.
---
# Query ECS instances
## Step
1. Confirm the query scope: region and filter conditions (instance status, tags, and so on). If no region is specified, all regions are queried by default.
2. Run the tools/query-instances.py command to specify the region and filter conditions to obtain the instance list. Refer to 'references/instance-status-codes.md to interpret the status code.
3. Refer to the template in 'assets/output-template.md and output the query result in the following format:
-Query summary (region, total number of instances)
-Instance list (instance name, instance ID, status, instance type, and IP address)
4. If the user needs to export the results, execute 'tools/export-csv.py to generate CSV file. The SKILL.md consists of two parts: the YAML metadata (name and description) at the top and the Markdown body. Files in references/, tools/, and assets/ are referenced in the body by relative paths, separating reference data, scripts, and templates from execution logic.
Step 2: Import the project
Place the Skill folder in a path that the smart body platform can recognize. Common Platform Promised Paths:
Platform | Skill Path | Description |
Spirit Code |
| Automatic discovery by convention directory |
Cursor |
| Loading via Rules or Agent Configuration |
Claude Code |
| Automatically scan all Skill in the directory |
For example, in Claude Code, move the skills/ecs-query folder under .claude/skills/ to complete the import.
Step 3: Verify the effect
After the import is complete, enter the task instruction to the smart body, and the smart body will automatically match and load according to the description of each Skill.
For example, in Claude Code, enter:
Check which ECS instances are running in the China (Hangzhou) region.The smart body matches the ecs-query Skill and returns the result in the format defined in the SKILL.md:
ECS instance query result
Query Summary:
-Region: China (Hangzhou)
-Running instance: 3
Instance list:
| Instance name | Instance ID | Status | Specification | 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 | The file format, content structure, and security policies of Skill may vary based on different platforms. For specific requirements, see the documentation of the corresponding platform.