YouTip

SKILL.md File | Beginner's Tutorial SKILL.md is the core file for Agent Skills. This section will provide an in-depth explanation of the complete structure and all available fields of SKILL.md. * * * ## Basic Structure A SKILL.md file contains two main parts: 1. YAML Frontmatter (metadata area) 2. Markdown content (instruction area) ## Complete Example --- name: my-skill description: Skill description, telling us when to use this skill license: Apache-2.0 compatibility: Requires Python 3.10+ metadata: author: your-name version: "1.0" --- # Skill Name Here are the detailed instructions for the skill... ## Step One Specific operation steps... ## Step Two More operation steps... * * * ## Metadata Fields Explained Below are all metadata fields supported by SKILL.md: | Field | Required | Constraints | | --- | --- | --- | | name | Yes | Maximum 64 characters, only lowercase letters, numbers, and hyphens allowed, cannot start or end with a hyphen | | description | Yes | Maximum 1024 characters, describing the skill's function and usage scenarios | | license | No | License name or reference to bundled license file | | compatibility | No | Maximum 500 characters, describing environment requirements (target product, system packages, network access, etc.) | | metadata | No | Arbitrary key-value pairs for storing additional metadata | | allowed-tools | No | Space-separated list of pre-approved tools (experimental feature) | * * * ## name Field Explained The name field is the identifier for the skill and must follow these rules: * Length: 1-64 characters * Character restrictions: Only Unicode lowercase letters (a-z) and hyphens (-) * Start and end: Cannot start or end with a hyphen * Consecutive characters: Cannot contain consecutive hyphens (--) * Matching requirement: Must match the parent directory name Valid examples: name: pdf-processing name: data-analysis name: code-review Invalid examples: name: PDF-Processing # Error: uppercase letters not allowed name: -pdf # Error: cannot start with a hyphen name: pdf--processing # Error: cannot contain consecutive hyphens * * * ## description Field Explained The description field is one of the most important fields, as it tells the agent when this skill should be activated. A good description should: * Describe the skill's function (what it does) * Explain usage scenarios (when to use it) * Include keywords to help the agent identify relevant tasks Good description example: description: Extract text and tables from PDF files, fill PDF forms, merge multiple PDFs. Use when processing PDF documents or when users mention PDFs, forms, or document extraction. Bad description example: description: Helps process PDF files. # Too vague, agent cannot determine when to use > Tip: The description field is loaded when the conversation starts. Ensure it contains sufficient keywords so the agent can correctly identify when this skill needs to be activated. * * * ## license Field Explained The license field is used to specify the skill's license. This is an optional field. license: Apache-2.0# or reference a bundled license file license: Proprietary. LICENSE.txt has complete terms * * * ## compatibility Field Explained The compatibility field is used to describe the skill's environment requirements. Only add this when the skill has special environment requirements. # Specify target product compatibility: Designed for Claude Code# Specify system dependencies compatibility: Requires git, docker, jq, and access to the internet # Specify programming language version compatibility: Requires Python 3.14+ and uv > Note: Most skills do not need a compatibility field. Only add it when the skill truly has specific environment requirements. * * * ## metadata Field Explained The metadata field can store arbitrary key-value pair information. Clients can use it to store additional attributes not defined in the specification. metadata: author: example-org version: "1.0" tags: - pdf - document - extraction > Tip: It is recommended to use relatively unique key names to avoid conflicts with other skills. * * * ## allowed-tools Field Explained allowed-tools is an experimental field used to specify pre-approved tools that the skill can use. allowed-tools: Bash(git:*) Bash(jq:*) Read > Note: This is an experimental feature, and different agent implementations may support it to varying degrees. * * * ## Instruction Area Explained The Markdown content after the metadata area is the instruction part of the skill. There are no format restrictions here; you can write anything as needed. It is recommended to include the following content: * Step-by-step operation instructions * Input and output examples * Common edge case handling # Skill Name## Function DescriptionBriefly describe what this skill does.## Operation Steps1. Step one: perform an action2. Step two: perform another action3. Step three: complete the final action## Examples### Input ExampleDescribe what the input is...### Output ExampleDescribe what the output is...## Notes- Note point 1- Note point 2 > Note: Once a skill is activated, the entire SKILL.md file is loaded into context. It is recommended to keep the main instructions within 500 lines and under 5000 tokens. Move detailed reference materials to separate files.