# 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 (`---`).

```markdown
---
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.