Andrew Yim
341d5f5a5b
Custom Skills (ourdigital-custom-skills/): - 00-ourdigital-visual-storytelling: Blog featured image prompt generator - 01-ourdigital-research-publisher: Research-to-publication workflow - 02-notion-organizer: Notion workspace management - 03-research-to-presentation: Notion research to PPT/Figma - 04-seo-gateway-strategist: SEO gateway page strategy planning - 05-gateway-page-content-builder: Gateway page content generation - 20-jamie-brand-editor: Jamie Clinic branded content GENERATION - 21-jamie-brand-guardian: Jamie Clinic content REVIEW & evaluation Refinements applied: - All skills converted to SKILL.md format with YAML frontmatter - Added version fields to all skills - Flattened nested folder structures - Removed packaging artifacts (.zip, .skill files) - Reorganized file structures (scripts/, references/, etc.) - Differentiated Jamie skills with clear roles 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
67 lines
4.5 KiB
Markdown
67 lines
4.5 KiB
Markdown
# 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. |