Skills Directory Structure
Understanding the directory structure and operating mechanism of a Skill is the foundation for building maintainable and reusable AI Agent capabilities.
This article breaks down the directory structure, the role of each file, and the complete workflow of a standard Skill from scratch.
What is a Skill
A Skill is an independent capability unit used to complete a specific type of task.
If the Agent is compared to an operating system, a Skill is like an application; if the Agent is compared to a project manager, a Skill is a professional capability that can be invoked.
Common Types of Skills
The following are some typical Skill application scenarios:
| Type | Description | Applicable Scenarios |
|---|---|---|
| PDF Document Analysis | Extract PDF content and generate summaries | Document processing, information extraction |
| Web Scraping | Automatically obtain web data | Data collection, information monitoring |
| SQL Optimization | Analyze and optimize SQL queries | Database performance tuning |
| Data Statistics | Data calculation and statistical processing | Data analysis, report generation |
| Image Recognition | Recognize content in images | OCR, image classification |
Relationship Between Skill and Agent
A Skill itself is not responsible for deciding when to be used; the Agent is the one that actually makes the decision.
The complete workflow is as follows:
Key point: The Agent does not load the full content of all Skills at once. It first reads the description information of each Skill, and only after matching the target Skill does it load the full content. The reason for this is: if there are hundreds of Skills, loading all of them every time would be extremely wasteful of Tokens.
Standard Directory Structure of a Skill
A complete Skill is not a single file, but a directory containing multiple files.
The following is the complete directory structure of a standard Skill:
my-skill/ │ ├── SKILL.md ← 核心执行文件 ├── metadata.json ← 元信息 ├── examples/ ← 示例目录 │ ├── example1.md │ └── example2.md │ ├── scripts/ ← 可执行脚本 │ ├── main.py │ └── utils.py │ ├── resources/ ← 资源目录 │ ├── prompt.md │ └── config.yaml │ ├── tests/ ← 测试目录 │ ├── test_cases.md │ └── eval.yaml │ ├── README.md ← 使用说明 │ └── CHANGELOG.md ← 变更日志
Next, we will break down the purpose of each file and directory one by one.
SKILL.md: Core Execution File
This is the most important file in a Skill, defining all the execution logic of the Skill.
It contains the following key information:
| Section | Description | Purpose |
|---|---|---|
| Description | Functional description of the Skill | Used for Agent matching |
| When to use | Clearly define applicable scenarios | Avoid false triggering |
| When NOT to use | Clearly define inapplicable scenarios | Prevent conflicts with other Skills |
| Input | Define input format | Standardize invocation method |
| Instructions | Execution steps | Guide task execution |
| Output | Output format description | Ensure consistency of results |
The following is a standardized SKILL.md example:
Example
## Description
Used to analyze PDF content and generate summaries.
## When to use
Suitable for:
- PDF reading
- Summary extraction
- Content analysis
## When NOT to use
Not suitable for:
- Image editing
- Video processing
## Input
PDF file
## Instructions
1. Extract text
2. Identify chapter structure
3. Summarize main content
4. Output key points
## Output
Markdown format summary
Common Incorrect Writing Styles
Many beginners write an overly simplified SKILL.md, for example:
Discouraged Writing Example
Read PDF
Summarize content
Return result
The problem with this writing style is: it doesn't know when to use it, doesn't know when not to use it, the output format is unclear, and it is easy to conflict with other Skills.
A qualified SKILL.md should allow the Agent to judge at a glance: whether this Skill is suitable for the current task.
metadata.json: Skill Metadata
This file provides machine-readable structured data to help the Agent quickly filter Skills.
Example
"name": "pdf-analyzer",
"version": "1.0.0",
"description": "Analyze PDF and generate a summary",
"tags": ["pdf", "summary"],
"category": "document"
}
Common Field Descriptions
| Field | Purpose | Importance |
|---|---|---|
| name | Skill Name | Required |
| description | Functional description; the Agent relies on it for matching | Most important |
| version | Version Number | Recommended |
| tags | Tags, for easy retrieval | Recommended |
| category | Category | Optional |
| author | Author | Optional |
| permissions | Required Permissions | Optional |
Among them,descriptionThe field is the most important because the Agent usually relies on it for matching.
The matching process is roughly as follows: after the user makes a request, the Agent scans the descriptions of all Skills, and after finding a matching description, loads the complete Skill content and executes it.
examples: Example Directory
Many developers ignore this part, but it is actually very important.
Directory Structure
examples/ ├── example1.md ├── example2.md
Example File Content
Example
Please help me analyze this PDF
Output:
# Document Summary
## Core Content
1. ...
2. ...
3. ...
Purpose of examples
| Purpose | Description |
|---|---|
| Provide Few-shot examples | Help the model understand expected behavior through examples |
| Standardize output format | Clarify output structure and style through examples |
| Improve output stability | Reduce random behavior and make results more predictable |
Empirically, good examples are often more effective than adding more prompts.
scripts: Executable Scripts
A Skill is not just a prompt; sometimes it is necessary to actually execute code to complete real work.
Common scenarios requiring scripts include: reading PDFs, executing OCR, calling databases, data processing, generating charts, etc.
Directory Structure
scripts/ ├── main.py └── utils.py
Python Script Example
Example
# Function: Extract text content from PDF file
from pypdf import PdfReader
# Open PDF file
reader = PdfReader("demo.pdf")
# Store extracted text
text = ""
# Iterate through each page and extract text
for page in reader.pages:
text += page.extract_text()
# Output all text content
print(text)
The Skill workflow is: read file → execute script → get result, then hand the result to the large model for processing.
resources: Resource Directory
Used to store auxiliary content, separating configuration from code.
Directory Structure
resources/ ├── prompt.md ├── config.yaml
Possible Resource Types
| Resource type | Description | Example |
|---|---|---|
| Prompt template | Reusable prompt templates | prompt.md |
| Configuration file | Parameters and settings | config.yaml |
| Text templates | Email, report templates | template.txt |
| Image resources | Icons, diagrams | logo.png |
| SQL templates | Predefined query templates | query.sql |
Configuration File Example
Example
# Summary-related configuration
max_length: 1000 # Maximum summary length (characters)
language: zh # Output language: zh=Chinese, en=English
Putting configuration in a separate file means you don't need to change code when modifying parameters later.
tests: Test Directory
Mature projects usually include tests to verify the effectiveness and stability of the Skill.
Directory Structure
tests/ ├── test_cases.md └── eval.yaml
Test Case Example
Example
Input:
Help me analyze the PDF
Expected:
Output a summary
Include key points
Purpose of Testing
| Purpose | Description |
|---|---|
| Verify effectiveness | Ensure the Skill output meets expectations |
| Regression testing | After modifications, verify old functionality is unaffected |
| Automated evaluation | Batch testing with automated workflows |
| A/B testing | Compare output quality of different versions |
Skills without testing are prone to the problem of "changing one sentence suddenly breaks old functionality."
README: Usage Instructions
README is intended for developers, explaining how to install and use this Skill.
Example
Copy to the skills directory
# Usage
Upload PDF
# Output format
Markdown
The core problem it solves is: in the future, even the author may not know how to use the Skill they wrote.
Complete Example: PDF Analysis Skill
Below is a complete example that ties together all the above concepts.
Directory Structure Overview
pdf-analyzer/ ├── SKILL.md ├── metadata.json ├── examples/ │ └── summary.md ├── scripts/ │ └── extract.py ├── tests/ │ └── eval.md └── README.md
Complete Invocation Flow
用户：
上传 PDF 并总结
↓
Agent：
扫描所有 Skills
↓
发现：
description: 分析 PDF 并生成摘要
↓
命中 pdf-analyzer
↓
读取 SKILL.md
↓
调用 extract.py
↓
提取 PDF 内容
↓
生成摘要
↓
返回结果
Why Design Skills as a Directory Structure?
Many people ask: why not just use a single prompt.txt to handle everything?
The reason is that things get out of control as the scale grows.
Problems with the Single-File Approach
| Problem | Specific manifestation |
|---|---|
| Not maintainable | All content piled into one file, making modifications difficult |
| Not testable | No test cases, so you don't know if it works after changes |
| Not reusable | Every Skill has to be written from scratch |
| No version management | Difficult to track change history |
| No multi-person collaboration | Multiple people modifying one file easily causes conflicts |
Advantages of the Directory-Based Approach
| Advantage | Implementation method |
|---|---|
| Maintainable | Each file has clear responsibilities, quick to locate modifications |
| Reusable | Scripts and configurations can be shared across Skills |
| Testable | Independent test directory, supports automated verification |
| Extensible | Adding new features only requires adding files |
| Publishable | The directory can be packaged and distributed |
Summary
A Skill is essentially not a prompt, but a complete software capability package.
Core File Relationships
SKILL.md
↓
定义行为
metadata.json
↓
定义信息
examples/
↓
定义示例
scripts/
↓
定义能力
tests/
↓
定义质量
README
↓
定义使用方式
Other extensionsA prompt only solves a problem once, while a Skill turns capability into an asset.