YouTip

Understanding the directory structure and operation mechanism of a Skill is the foundation for building maintainable and reusable AI Agent capabilities. This article breaks down the standard directory structure, file roles, and complete workflow of a Skill from scratch. * * * ## What is a Skill A Skill is an independent capability unit designed to complete a specific type of task. If we compare an Agent to an operating system, a Skill is like an application; if we compare an Agent to a project manager, a Skill is the professional expertise that can be called upon. ### Common Types of Skills Here 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 retrieve 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 | Identify content in images | OCR, image classification | ### Relationship Between Skill and Agent The Skill itself does not decide when to be used; the Agent is responsible for making that decision. The complete workflow is as follows:  > Key Point: The Agent does not load the complete content of all Skills at once. It first reads the description information of each Skill, and only loads the full content after matching the target Skill. 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. Below is the complete directory structure of a standard Skill: my-skill/│├── SKILL.md ← Core execution file├── metadata.json ← Metadata├── examples/ ← Example directory│ ├── example1.md │ └── example2.md │├── scripts/ ← Executable scripts│ ├── main.py │ └── utils.py │├── resources/ ← Resource directory│ ├── prompt.md │ └── config.yaml │├── tests/ ← Test directory│ ├── test_cases.md │ └── eval.yaml │├── README.md ← Usage instructions│└── CHANGELOG.md ← Change log Next, we will break down the role of each file and directory one by one. !(#) * * * ## SKILL.md: Core Execution File This is the most important file in a Skill, defining all execution logic of the Skill. It contains the following key information: | Section | Description | Purpose | | --- | --- | --- | | Description | Functional description of the Skill | Used by the Agent for matching | | When to use | Clearly define applicable scenarios | Avoid false triggers | | 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 result consistency | Below is a standard SKILL.md example: ## Example # PDF Analysis Skill ## Description Used for analyzing PDF content and generating summaries. ## When to use Applicable to: - PDF reading - Summary extraction - Content analysis ## When NOT to use Not applicable to: - 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 Many beginners write overly simplified SKILL.md files, such as: ## Not Recommended # PDF Skill Read PDF Summarize content Return result The problem with this writing is: it doesn't specify when to use, when not to use, the output format is unclear, and it easily conflicts with other Skills. > A qualified SKILL.md should allow the Agent to determine 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 summary", "tags": ["pdf", "summary"], "category": "document" } ### Common Field Descriptions | Field | Purpose | Importance | | --- | --- | --- | | name | Skill name | Required | | description | Functional description, used by Agent for matching | Most important | | version | Version number | Recommended | | tags | Tags for easy retrieval | Recommended | | category | Category | Optional | | author | Author | Optional | | permissions | Required permissions | Optional | The description field is the most important, as the Agent typically 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, discovers matching descriptions, and then loads the complete Skill content for execution. * * * ## examples: Example Directory Many developers overlook this part, but it is actually very important. ### Directory Structure examples/├── example1.md ├── example2.md ### Example File Content ## Example Input: 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 | > In practice, good examples are often more effective than adding more prompt words. * * * ## scripts: Executable Scripts A Skill is not just about prompts; sometimes actual code execution is needed to complete the 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 # File path: scripts/extract.py # Function: Extract text content from PDF files 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 → obtain result, then pass 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 template | Email, report templates | template.txt | | Image resources | Icons, diagrams | logo.png | | SQL templates | Predefined query templates | query.sql | ### Configuration File Example ## Example # File path: resources/config.yaml # Summary-related configuration max_length: 1000# Maximum summary length (characters) language: zh # Output language: zh=Chinese, en=English Placing configurations in separate files means you don't need to modify code when changing parameters later. * * * ## tests: Test Directory Mature projects typically include tests to verify the effectiveness and stability of Skills. ### Directory Structure tests/├── test_cases.md └── eval.yaml ### Test Case Example ## Example Test: Input: Help me analyze PDF Expected: Output summary Contains key points ### Purpose of Tests | Purpose | Description | | --- | --- | | Verify effectiveness | Ensure Skill output meets expectations | | Regression testing | Verify old features are unaffected after modifications | | Automated evaluation | Support batch testing with automated processes | | A/B testing | Compare output quality of different versions | > Skills without tests are prone to "changed one sentence, old feature suddenly breaks" issues. * * * ## README: Usage Instructions README is aimed at developers, explaining how to install and use this Skill. ## Example # Installation Copy to skills directory # Usage Upload PDF # Output Format Markdown The core problem it solves: not even knowing how to use your own Skill later on. * * * ## Complete Case: PDF Analysis Skill Below is a complete example tying together all the concepts above. ### Directory Structure Overview pdf-analyzer/├── SKILL.md ├── metadata.json ├── examples/│ └── summary.md ├── scripts/│ └── extract.py ├── tests/│ └── eval.md └── README.md ### Complete Invocation Flow User: Upload PDF and summarize ↓Agent: Scan all Skills ↓Discover: description: Analyze PDF and generate summary ↓Match pdf-analyzer ↓Read SKILL.md ↓Call extract.py ↓Extract PDF content ↓Generate summary ↓Return result * * * ## Why Skills Are Designed as Directory Structures Many people ask: why not use a single prompt.txt to handle everything? The reason is that it becomes uncontrollable at scale. ### Problems with Single-File Solutions | Problem | Specific Manifestation | | --- | --- | | Unmaintainable | All content piled in one file, difficult to modify | | Untestable | No test cases, don't know if it works after changes | | Non-reusable | Each Skill has to be written from scratch | | No version management | Difficult to track change history | | No multi-person collaboration | Multiple people modifying one file causes conflicts | ### Advantages of Directory-Based Solutions | Advantage | Implementation | | --- | --- | | Maintainable | Clear responsibilities for each file, quick to locate modifications | | Reusable | Scripts and configurations can be shared across Skills | | Testable | Independent test directory, supports automated verification | | Extensible | New features only require adding files | | Publishable | 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 ↓Defines behavior metadata.json ↓Defines information examples/ ↓Defines examples scripts/ ↓Defines capabilities tests/ ↓Defines quality README ↓Defines usage > Prompts can only solve a problem once, while Skills transform capabilities into assets.