our-claude-skills/reference/skill-compact-guide.md

Custom Claude Skill Creation Reference

Claude Skills are portable, reusable folders that encapsulate domain-specific expertise, instructions, and optional code, transforming Claude from a general assistant into a specialized expert.

---

I. Skill Foundation

Component	Description
Concept	A directory (folder) that contains all necessary files.
Core File	Every skill requires a mandatory SKILL.md file.
Prerequisite	Code execution capability must be enabled on your Claude plan (Pro, Max, Team, or Enterprise) to upload and use custom skills.
Architecture	Follows Progressive Disclosure: only minimal metadata loads at startup; full instructions and resources load dynamically when the skill is triggered.

---

II. The Core File: SKILL.md Structure

The SKILL.md file combines mandatory metadata (Level 1) and procedural instructions (Level 2).

A. Level 1: YAML Frontmatter (Metadata)

This block must be at the very top of the file, enclosed in triple dashes (---).

---
name: your-skill-name
description: A clear explanation of what this skill does and when to use it.
---

Field	Requirement	Best Practice
name (Required)	Max 64 characters; lowercase letters, numbers, and hyphens only. Must not contain "anthropic" or "claude".	Use descriptive, concise names, often in the gerund form (e.g., processing-data).
description (Required)	Must be non-empty; max 1024 characters. This is the primary trigger for automatic activation.	Be highly specific. Include action verbs, file types, and explicit use cases to ensure reliable invocation (e.g., "Extract tables from PDF files and convert them to CSV format").
Optional	allowed-tools (e.g., "Read,Write,Bash"), version, license, model.	Only include tools the skill absolutely requires to minimize security risk and operational surface area.

B. Level 2: Instructions (Markdown Body)

This section contains the actual playbook Claude follows when the skill is active.

• Structure: Use clear Markdown headers (#, ##, ###) to organize content logically (e.g., ## Overview, ## Execution Steps, ## Error Handling).
• Directive Language: To maximize reliability and adherence, use strong, absolute language: MUST, NEVER, ALWAYS, and REQUIRED. Avoid suggestive words like "should" or "try to."
• Conciseness: Keep the main content concise (recommended under 500 lines) to avoid overwhelming the context window once the skill is loaded.

---

III. Optional Resources (Level 3 Assets)

Resources are optional files placed in subdirectories within the skill folder, used for deterministic actions or large reference materials. They consume zero context tokens unless explicitly accessed by Claude.

Folder	Purpose	Usage Note
scripts/	Executable code (Python, Bash) for deterministic operations (e.g., validation, sorting, API interaction).	Execution is faster and more reliable than having Claude generate equivalent code.
references/	Large text documents (e.g., API documentation, detailed style guides, database schemas) that Claude reads into context when referenced.	Use relative paths from SKILL.md to link directly to these files.
assets/	Templates or binary files (e.g., HTML boilerplate, images, configuration files) referenced by path but not read into context.	Claude interacts with these files primarily for copying or manipulation.

---

IV. Deployment and Iteration

1. Preparation: Organize your skill folder, ensuring it contains SKILL.md and any necessary subdirectories (scripts/, references/).
2. Deployment (Claude.ai): Compress the main skill folder into a .ZIP file, then upload it via Settings > Capabilities > Upload skill.
3. Deployment (Claude Code): Place the skill directory directly into the local ~/.claude/skills/ folder or the project-specific .claude/skills/ directory.
4. Testing and Refinement: Test the skill with real-world scenarios. If activation is inconsistent, refine the description field. If output is inconsistent, strengthen the mandatory instructions in the SKILL.md body using keywords like MUST and ALWAYS.
5. Iteration Loop: The recommended development process is: 1) Perform the task manually in a chat, 2) Ask Claude to create/update the skill based on the successful conversation steps, 3) Test and repeat.