DocsICP FilingConsole
Documentation
Home Page Cloud Agent Catalog Getting Started Learn about Agent Skills

Learn about Agent Skills

Updated at:
Copy as MD
Product
My Favorites

Agent Skills, or simply Skills, are collections of instructions and reference materials that agents load on demand, organized and version-managed as independent directories. At the core of each Skill is a SKILL.md file containing metadata and execution instructions, which the agent uses to decide when to load the Skill and how to execute it.

Why you need Skills

Skills package domain processes, tool usage, and organizational constraints into reusable file collections. Create them once and reuse them across multiple sessions and tasks to ensure consistent execution. Skills have the following core characteristics:

  • On-demand loading: The agent loads a Skill only when the task matches it, keeping irrelevant instructions from occupying the context window.

  • Reusable: The same Skill can be reused across different sessions and tasks without rewriting instructions.

  • Versionable: Skills are stored as files in a code repository, supporting Git version control, code review, and team collaboration.

  • Composable: Multiple Skills can work together. The agent dynamically schedules and combines them based on task requirements.

Skill structure

Each Skill is organized as an independent directory, usually following the Agent Skills specification with the following structure:

my-skill/
├── SKILL.md           # Required: main file with metadata and execution instructions
├── references/        # Optional: in-depth reference materials, field descriptions, decision tables
├── tools/             # Optional: helper scripts, code snippets
└── assets/            # Optional: diagrams, screenshots, CSVs, and other static resources

SKILL.md is the only required file. It consists of two parts: metadata and body.

  • Metadata: Contains at least name (a unique identifier) and description (applicable use cases and trigger conditions). The agent decides whether to load a Skill based on its description.

  • Body: Describes the operating procedure step by step. It may include conditional branches, checkpoints, and expected outputs, and defines clear success criteria.

How Skills work

Skills use progressive disclosure. Instead of loading the full content of every Skill at once, the agent loads them in phases and on demand to keep context usage under control:

  1. Discovery: When starting a task, the agent loads only the name (name) and description (description) from each Skill's metadata and evaluates their relevance to the current task.

  2. Activation: When a task matches a Skill's description, the agent reads the full SKILL.md file into its context.

  3. Execution: The agent follows the instructions in SKILL.md, loading referenced files or running the bundled scripts as needed.

Note

A Skill provides operating guidance only and does not replace the runtime environment or permission policies. Whether operations such as configuration changes or access to production data are allowed is still determined by the platform's identity, policies, and processes.

Usage example

This example creates a Skill with a complete directory structure for querying ECS instance status and verifies the result.

Step 1: Create the Skill directory

In the project directory, create a skills/ecs-query folder with the following structure:

ecs-query/
├── SKILL.md                       # Main file: metadata and execution instructions
├── references/
│   └── instance-status-codes.md   # ECS instance status codes and their meanings
├── tools/
│   ├── query-instances.py         # Calls the DescribeInstances API to query the instance list
│   └── export-csv.py              # Exports the query results to a CSV file
└── assets/
    └── output-template.md         # Output format template for query results

Create the SKILL.md file:

---
name: ecs-query
description: When the user wants to check the running status of ECS instances, call the DescribeInstances API to query and summarize the results.
---

# Query ECS instances

## Steps
1. Confirm the query scope: region and filter conditions (instance status, tags, etc.). If no region is specified, query all regions by default.
2. Run `tools/query-instances.py` with the region and filter conditions to get the instance list. Refer to `references/instance-status-codes.md` to interpret the status codes.
3. Follow the template in `assets/output-template.md` and output the query results in the following format:
   - Query summary (region, total number of instances)
   - Instance list (instance name, instance ID, status, instance type, IP address)
4. If the user wants to export the results, run `tools/export-csv.py` to generate a CSV file.

SKILL.md consists of two parts: the YAML metadata at the top (name and description) and the Markdown body. The body references files under references/, tools/, and assets/ by relative paths, separating reference data, scripts, and templates from the execution logic.

Step 2: Import into the project

Place the Skill folder in a path that your agent platform recognizes. Conventional paths for common platforms:

Platform

Skill path

Description

Qoder

.qoder/skills/

Discovered automatically from the conventional directory

Cursor

.cursor/skills/

Loaded via rules or agent configuration

Claude Code

.claude/skills/

Automatically scans all Skills in this directory

The table above shows examples only. For the full list of supported clients and installation paths, see Install and use your first Skill.

For example, in Claude Code, move the skills/ecs-query folder into .claude/skills/ to import it.

Step 3: Verify the result

After the import, give the agent a task instruction. The agent automatically matches it to a Skill and loads that Skill based on each Skill's description.

For example, enter the following in Claude Code:

Check which ECS instances are running in the China East 1 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 East 1 (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    |
Note

Skill file formats, content structures, and security policies may differ across platforms. Check your platform's documentation for specific requirements.

Official sources

Besides writing your own, you can get Skills from Agent Catalog. Agent Catalog is Alibaba Cloud's official distribution platform for Agent assets. It publishes officially verified Skills that you can install into your Agent client for free and use right away. For more information, see Learn about Agent Catalog.

References

Previous：Getting StartedNext：Learn about Agent Catalog