Skills Basic Structure |

\\n\\n

The core essence of Skills is to provide standardized execution process guidelines for AI. Once written, rules can be repeatedly invoked and directly reused, just like program functions.

\\n\\n

Skills are stored as Markdown text and do not execute functionality directly.

\\n\\n

With their on-demand loading and progressive invocation characteristics, Skills efficiently accumulate work experience, enabling rapid reuse and precise transfer of capabilities.

\\n\\n

---

\\n\\n

Skill Core Structure

\\n\\n

The core of Skills is: one folder + one SKILL.md file.

\\n\\n

The SKILL.md file contains:

\\n\\n

\\n
• Metadata (must include at least name and description)
\\n
• Instructions telling the AI how to complete a specific task
\\n

\\n\\n

\\n\\n

A Skill is essentially a Markdown file (filename fixed as SKILL.md)

\\n\\n

my-skill/\\n└── SKILL.md (the only required file)\\n

\\n\\n

SKILL.md Basic Template:

\\n\\n

---\\nname: your-skill-name\\ndescription: Describe the capabilities and use scenarios of This Skill in one sentence\\n---\\n# Skill Name\\n## UseGuidelines\\n\\n## Example\\n\\n

\\n\\n

The entire SKILL.md is divided into two parts: the YAML frontmatter (header configuration) wrapped by ---, and the Markdown body below (execution instructions).

\\n\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n

Field	Required	Description	Example
name	Yes	Unique identifier for the Skill, using kebab-case naming. Referenced by the / command and critical for system Skill recognition.	web-design-guidelines
description	Yes	One-sentence description of functionality and trigger scenarios. More specific content leads to more accurate triggering.	UI/UX design review for web pages

\\n\\n

Next, we break down each part individually:

\\n\\n

\\n\\n

Frontmatter: Two Required Fields

\\n\\n

Frontmatter is the YAML configuration block wrapped by --- at the top of SKILL.md, representing the Skill’s identity information.

\\n\\n

The official specification defines only two required fields:

\\n\\n

Field 1: name (Skill Name)

\\n\\n

The name field can be up to 64 characters long and may only contain lowercase letters, digits, and hyphens.

\\n\\n

name: processing-pdfs # Good: gerund form, clearly describes functionality\\nname: analyzing-spreadsheets # Good: purpose is immediately clear\\nname: my-brand-guidelines # Good: organization-specific knowledge\\nname: helper # Bad: too vague\\nname: MySkill # Bad: contains uppercase letters (non-compliant)\\nname: data files # Bad: contains spaces (non-compliant)\\n

\\n\\n

It is recommended to use gerund forms (verb + -ing) for naming, such as processing-pdfs and analyzing-spreadsheets, to clearly describe the activity or capability provided by the Skill.

\\n\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n

Recommended	Not Recommended	Reason
code-reviewer	CodeReviewer	Use lowercase and hyphens consistently to avoid cross-platform compatibility issues
sql-optimizer	sql_optimizer	Kebab-case is the conventional format and aligns with directory naming
deploy-check	deploy-check-tool-v2	Names should be concise; version info belongs in internal documentation

\\n\\n

Field 2: description (Trigger Condition Description)

\\n\\n

This is the most important field. During startup, the system only preloads all Skills’ name and description into the system prompt.

\\n\\n

Only when the description is judged by the AI to be relevant to the current task will the full SKILL.md content be loaded.

\\n\\n

The description should include two parts: what this Skill does and when Claude should use it.

\\n\\n

description: |\\n  Use when the user needs to create, read, edit, or generate Word documents (.docx). Triggers include: 'Word doc', 'word document', '.docx', 'report', 'letter', 'memo', or any request to produce a formatted document for sharing or printing.\\n

\\n\\n

\\n\\n

Markdown Body: Internal Structure of Execution Instructions

\\n\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n

Recommended	Not Recommended	Reason
「Scan Python code for SQL injection risks and provide remediation suggestions」	「A security tool」	Description too vague to trigger accurately
「Convert Markdown into brand-compliant HTML emails」	「Convert file formats」	Lacks specific context; may be mistakenly triggered in other tasks

\\n\\n

After the frontmatter comes the Markdown body, which tells the AI how to perform the task.

\\n\\n

It must contain at least two sections:

\\n\\n

\\n\\n

SKILL.md Example

\\n\\n

SKILL.md Basic Template:

\\n\\n

---\\nname: pdf-processing\\ndescription: From PDF Extract text and tables, fill out forms, and merge documents\\n---\\n# PDF Handle.\\n## UseScenarios\\nUse when operations on PDF files are required, for example:\\n- Extract text or table data from PDFs\\n- Fill out PDF forms\\n- Merge multiple PDF files\\n\\n## Extract text\\n- Use `pdfplumber` Extract content from text-based PDFs\\n- Scanned PDFs require OCR tools\\n\\n## Fill out forms\\n- Read PDF form fields\\n- Populate and generate new files based on input data\\n

\\n\\n

Minimum Required Example:

\\n\\n

---\\nname: skill-name\\ndescription: Describe the capabilities of This Skill and applicable scenarios\\n---\\n

\\n\\n

Example with Optional Fields:

\\n\\n

---\\nname: pdf-processing\\ndescription: From PDF Extract text and tables, fill out forms, and merge documents\\nlicense: Apache-2.0\\nmetadata:\\n  author: example-org\\n  version: "1.0"\\n---\\n

\\n\\n

Field Descriptions:

\\n\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n

Field	Required	Description
name	Yes	Skill name, up to 64 characters, only lowercase letters, digits, and - allowed; cannot start or end with -
description	Yes	Functionality and usage scenario description, up to 1024 characters, cannot be empty
license	No	License name or path to the license file bundled with the Skill
compatibility	No	Environment and dependency description (products, system packages, network permissions, etc.), up to 500 characters
metadata	No	Custom key-value pairs for extending metadata (e.g., author, version number)
allowed-tools	No	List of allowed tools (space-separated; experimental feature)

\\n\\n

---

\\n\\n

Skill File Directory Structure

\\n\\n

Each Skill is a folder containing at least one SKILL.md file. Additional directories and files may be added as needed.

\\n\\n

To avoid context bloat:

\\n\\n

\\n
• Core rules → SKILL.md
\\n
• Detailed materials → separate files
\\n
• Practical logic → script execution (not loaded)
\\n

\\n\\n

Recommended Structure:

\\n\\n

my-skill/\\n├── SKILL.md           # Required: metadata + instructions\\n├── scripts/           # Optional: executable code\\n│   └── helper.py\\n├── references/        # Optional: reference documents\\n├── assets/            # Optional: templates, resources\\n└── ...                # Other files or directories\\n

\\n\\n

Directory purposes:

\\n\\n

\\n
• SKILL.md: Required file containing the Skill’s metadata and execution instructions
\\n
• scripts/: Optional directory containing executable code the agent can run
\\n
• references/: Optional directory containing detailed reference materials
\\n
• assets/: Optional directory containing static resources such as templates and images
\\n

\\n\\n