Hướng dẫn xây dựng Skill cho Claude

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

description: >
  Manages Linear project workflows including sprint planning,
  task creation, and status tracking. Use when user mentions
  "sprint", "Linear tasks", "project planning", or asks to
  "create tickets".

description: Helps with projects.   # quá chung
description: Creates sophisticated multi-page documentation systems.  # thiếu trigger

# Your Skill Name

## Instructions

### Step 1: [first major step]
Clear explanation of what happens.

Example:

Expected output: [describe what success looks like]

## Examples

### Example 1: [common scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [common error message]
Cause: [why it happens]
Solution: [how to fix]

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (nếu skill không xử lý sheet)

Without skill:                With skill:
- 15 back-and-forth msg       - Automatic workflow
- 3 failed API calls          - 2 clarifying questions only
- 12,000 tokens               - 0 failed API calls
                              - 6,000 tokens

[ ] Folder name kebab-case, không space/capital
[ ] File tên đúng SKILL.md (case-sensitive)
[ ] Frontmatter có --- ở đầu và cuối
[ ] name: kebab-case, không capital
[ ] description: có cả WHAT và WHEN, < 1024 ký tự
[ ] Không có XML tag (< >) trong frontmatter
[ ] Instructions rõ ràng, có ví dụ
[ ] Có troubleshooting section
[ ] Reference link tới references/ rõ ràng
[ ] Không có README.md trong skill folder
[ ] Đã test trigger trên prompt obvious + paraphrased
[ ] Đã test không trigger trên prompt unrelated
[ ] Functional test pass

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

description: >
  Manages Linear project workflows including sprint planning,
  task creation, and status tracking. Use when user mentions
  "sprint", "Linear tasks", "project planning", or asks to
  "create tickets".

description: Helps with projects.                                  # too vague
description: Creates sophisticated multi-page documentation systems.  # missing triggers

# Your Skill Name

## Instructions

### Step 1: [first major step]
Clear explanation of what happens.

Example:

Expected output: [describe what success looks like]

## Examples

### Example 1: [common scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [common error message]
Cause: [why it happens]
Solution: [how to fix]

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (unless your skill handles sheets)

Without skill:                With skill:
- 15 back-and-forth msgs      - Automatic workflow
- 3 failed API calls          - 2 clarifying questions only
- 12,000 tokens               - 0 failed API calls
                              - 6,000 tokens

[ ] Folder name kebab-case, no spaces or capitals
[ ] File named exactly SKILL.md (case-sensitive)
[ ] Frontmatter has --- delimiters at top and bottom
[ ] name: kebab-case, no capitals
[ ] description: includes WHAT and WHEN, under 1024 chars
[ ] No XML tags (< >) anywhere in frontmatter
[ ] Instructions are clear with examples
[ ] Troubleshooting section present
[ ] Reference links to references/ are explicit
[ ] No README.md inside the skill folder
[ ] Triggering tested on obvious + paraphrased prompts
[ ] Verified it doesn't trigger on unrelated prompts
[ ] Functional tests pass

**TL;DR**

Theo Anthropic, **skill là một bộ chỉ dẫn — đóng gói thành một folder đơn giản — dạy Claude cách xử lý một loại task hoặc workflow cụ thể**. Khác với việc lặp lại preferences và quy trình trong mỗi cuộc hội thoại, skill cho phép bạn _dạy Claude một lần và dùng lại mãi_.



Skill phát huy sức mạnh khi bạn có **workflow lặp đi lặp lại**: tạo giao diện từ spec theo cùng một style, viết nghiên cứu, báo cáo theo cùng một phương pháp luận, tạo tài liệu hướng dẫn theo phong cách của team, hoặc điều phối thực hiện các tác vụ thông qua MCP.
Ví dụ kết hợp với các agent

Thực thi qua MCP:



     Bước 1: Agent gọi MCP Server của GitHub để đọc nội dung file.

     Bước 2: Agent tự phân tích và sửa lỗi (xử lý nội tại).

     Bước 3: Agent gọi MCP Server của File System để lưu bản nháp local.

     Bước 4: Agent gọi MCP Server của Slack để nhắn tin cho bạn.

Bài này tổng hợp lại tài liệu chính thức theo hướng dùng được — đủ để bạn build một skill chạy được trong 15-30 phút.

## Skill là gì — về mặt cấu trúc

Một skill là một thư mục chứa:

- **\`SKILL.md\`** _(bắt buộc)_ — file Markdown với YAML frontmatter ở đầu.
- **\`scripts/\`** _(tuỳ chọn)_ — code thực thi được (Python, Bash, …).
- **\`references/\`** _(tuỳ chọn)_ — tài liệu chi tiết, load khi cần.
- **\`assets/\`** _(tuỳ chọn)_ — template, font, icon dùng trong output.

Thư mục đặt tên **kebab-case** (ví dụ: `notion-project-setup`). Không space, không underscore, không capital. File **phải** đặt đúng tên `SKILL.md` (case-sensitive). Và **không** kèm `README.md` bên trong skill — README chỉ ở repo cấp ngoài cho người đọc.

## Progressive disclosure (tiết lộ dần) — vì sao skill khác CLAUDE.md

Skill dùng cơ chế ba tầng:

1. **YAML frontmatter** — luôn nằm trong system prompt. Đủ ngắn để Claude biết _khi nào_ cần dùng skill, mà không phải load toàn bộ.
1. **Phần thân \`SKILL.md\`** — load khi Claude thấy skill liên quan tới task hiện tại. Chứa instructions đầy đủ.
1. **File liên kết** (`references/`, `scripts/`, …) — Claude tự navigate tới khi cần.

Điểm khác biệt với `CLAUDE.md`: `CLAUDE.md` load **mỗi session**. Skill load **on-demand (khi cần)**. Nếu bạn có 30 quy trình lĩnh vực cụ thể, đẩy vào `CLAUDE.md` sẽ làm context phình ra và Claude bắt đầu bỏ qua chỉ dẫn — _"Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"_ Tách thành skill là cách giải quyết.

## Khi nào nên build skill

Anthropic chia ra ba category phổ biến:

- **Khởi tạo Tài liệu & Tài nguyên — **Đảm bảo đầu ra nhất quán: từ các file docx, pptx, xlsx cho đến thiết kế frontend hay các thành phần code (code component) đều tuân thủ đúng style guide. Tích hợp sẵn các tiêu chuẩn thương hiệu, biểu mẫu (template) và danh sách kiểm định chất lượng. Không cần thông qua MCP.
- **Workflow Automation** — quy trình nhiều bước cần phương pháp nhất quán, có kiểm tra xác thực, sàng lọc qua giữa các bước. Ví dụ: **skill-creator của Claude giúp bạn tạo skill theo chuẩn**.
- **MCP Enhancement** — bạn đã có MCP server, skill là _knowledge layer_ ở trên: dạy Claude dùng MCP đúng workflow, đúng thứ tự, có error handling.

Nếu bạn đang làm việc với MCP, thì kỹ năng quan trọng nhất chính là biến việc truy cập công cụ thô (raw tool access) thành những quy trình công việc (workflow) đáng tin cậy. Anthropic đã đưa ra một phép ẩn dụ về nhà bếp: MCP cung cấp cho bạn một gian bếp chuyên nghiệp (bao gồm công cụ và nguyên liệu), còn kỹ năng của bạn chính là công thức nấu ăn — tức là cách kết hợp chúng để tạo ra một món ăn có giá trị.

## YAML frontmatter — phần quan trọng nhất

Đây là cái duy nhất Claude **luôn** đọc để quyết định có load skill hay không. Format tối thiểu:

```yaml
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---
```

Quy tắc của `description`:

- **Phải có cả hai**: skill _làm gì_ + _khi nào dùng_ (trigger conditions).
- Dưới 1024 ký tự, không XML tag (`<` `>`).
- Liệt kê cụm từ cụ thể user có thể nói.
- Nếu liên quan đến file type, nêu rõ.

Ví dụ tốt:

```yaml
description: >
  Manages Linear project workflows including sprint planning,
  task creation, and status tracking. Use when user mentions
  "sprint", "Linear tasks", "project planning", or asks to
  "create tickets".
```

Ví dụ tệ — Claude sẽ không bao giờ trigger:

```yaml
description: Helps with projects.   # quá chung
description: Creates sophisticated multi-page documentation systems.  # thiếu trigger
```

Mẹo debug khi skill không trigger: hỏi Claude _"When would you use the \[skill name\] skill?"_ — Claude sẽ quote lại description. Đọc câu trả lời để biết bạn đang thiếu gì.

**Cấm trong frontmatter**: XML angle bracket (`<` `>`), tên skill chứa `"claude"` hoặc `"anthropic"` (reserved). Frontmatter hiện ra trong system prompt nên bị giới hạn để chống prompt injection.

## Cấu trúc phần thân SKILL.md

Sau frontmatter là Markdown thuần. Template Anthropic gợi ý:

```markdown
# Your Skill Name

## Instructions

### Step 1: [first major step]
Clear explanation of what happens.

Example:
```

python scripts/fetch_data.py --project-id PROJECT_ID

```
Expected output: [describe what success looks like]

## Examples

### Example 1: [common scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [common error message]
Cause: [why it happens]
Solution: [how to fix]
```

Nguyên tắc viết:

- **Specific & actionable** — _"Run \`python scripts/validate.py --input {filename}\` to check data format"_ thay vì _"Validate the data before proceeding"_.
- **Reference rõ ràng** — _"Before writing queries, consult \`references/api-patterns.md\` for rate limiting, pagination, and error codes."_
- **Giữ \`SKILL.md\` ngắn** — dưới ~5,000 từ. Tài liệu chi tiết đẩy sang `references/`.
- **Những hướng dẫn quan trọng phải nằm đầu** — Claude đọc theo thứ tự, đừng chôn ở cuối.
- **Ngôn ngữ rõ ràng** — _"CRITICAL: Before calling create_project, verify name is non-empty"_ thắng _"Make sure to validate things properly"\_.

Với validation _thật sự_ quan trọng, đừng dựa vào ngôn ngữ — _"Code is deterministic; language interpretation isn't."_ Bundle script và gọi nó trong instruction.

## Năm pattern thường gặp

Không phải template bắt buộc, là pattern cộng đồng đã chạy thành công:

**1. Điều phối theo trình tự (Sequential Workflow)**

Hiểu đơn giản: Làm việc theo kiểu "dây chuyền". Bước A xong mới tới bước B, nếu bước B lỗi thì phải biết quay lại xử lý hoặc hủy bỏ (rollback) để tránh sai sót hệ thống.

Ví dụ: Quy trình đón khách hàng mới.

Tạo tài khoản → Thiết lập thanh toán → Đăng ký gói dịch vụ → Gửi email chào mừng.

Nếu thanh toán lỗi, hệ thống sẽ dừng lại và không gửi email chào mừng vô duyên.



**2. Phối hợp đa công cụ (Multi-MCP Coordination)**

Hiểu đơn giản: Một "nhạc trưởng" điều khiển nhiều nhạc công (MCP) cùng lúc. Quan trọng nhất là dữ liệu từ công cụ này phải truyền sang công cụ kia trơn tru.

Ví dụ: Từ thiết kế ra sản phẩm thực tế.

Lấy ảnh từ Figma → Lưu vào Google Drive → Tạo nhiệm vụ trên Linear → Báo tin nhắn qua Slack.



**3. Cải thiện lặp lại (Iterative Refinement)**

Hiểu đơn giản: Làm nháp rồi sửa, sửa đến khi nào đạt chuẩn thì thôi. Thay vì bắt Claude làm một lần ra kết quả hoàn hảo, hãy cho nó "soát lỗi" nhiều lần.

Cách làm: Viết bản thảo → Chạy lệnh kiểm tra (validation) → Sửa dựa trên lỗi → Hoàn thiện.

Lưu ý: Phải dạy Claude biết thế nào là "đạt" và khi nào thì nên dừng lại để tránh lặp vô tận.



**4. Chọn công cụ theo ngữ cảnh (Context-aware Tool Selection)**

Hiểu đơn giản: "Tùy cơ ứng biến". Cùng một mục đích là lưu trữ, nhưng tùy loại file mà Claude sẽ chọn nơi cất giữ thông minh nhất.

Ví dụ: \* File nặng? Đẩy lên Cloud.

Tài liệu cần làm chung? Cho vào Notion.

Code? Đẩy lên GitHub.

File tạm? Lưu máy cục bộ.



**5. Trí tuệ chuyên biệt (Domain-specific Intelligence)**

Hiểu đơn giản: Không chỉ là biết dùng công cụ, mà còn phải có "đầu óc" của chuyên gia trong ngành đó. Skill này cài cắm các kiến thức nghiệp vụ sâu.

Ví dụ: Quy trình thanh toán quốc tế.

Claude không chỉ bấm nút "Chuyển tiền", mà nó còn biết tự kiểm tra danh sách đen (sanctions list), đánh giá rủi ro xem có dấu hiệu lừa đảo không, sau đó mới thực hiện và ghi lại nhật ký kiểm toán (audit trail).Một câu hỏi định hướng: skill của bạn là **problem-first** ("tôi cần set up workspace" → skill chọn tool) hay **tool-first** ("tôi đã connect Notion MCP" → skill dạy workflow tối ưu)? Đa số skill nghiêng về một phía. Biết được phía nào giúp bạn chọn pattern.

## Testing — ba loại test cần có

Thứ tự đề xuất từ Anthropic:

### 1. Triggering tests

Skill load đúng lúc, không load nhầm.

```
Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (nếu skill không xử lý sheet)
```

Mục tiêu: trigger trên **90%** query liên quan, gần 0% query không liên quan.

### 2. Functional tests

Chạy workflow → kiểm output. Ví dụ: "Create project with 5 tasks" → project được tạo, 5 task có property đúng, link đầy đủ về project, không API error.

### 3. Performance comparison

So với baseline (không có skill). Ví dụ:

```
Without skill:                With skill:
- 15 back-and-forth msg       - Automatic workflow
- 3 failed API calls          - 2 clarifying questions only
- 12,000 tokens               - 0 failed API calls
                              - 6,000 tokens
```

**Pro tip từ Anthropic**: lặp đi lặp lại trên **một** task khó tới khi Claude làm được, _rồi mới_ trích xuất thành skill. Đó là cách nhanh nhất, tận dụng việc học trong bối cảnh thực tế. Sau đó mới mở rộng test cases.

## Khi skill không trigger / trigger sai

**Undertriggering** (không load khi cần):

- Description quá chung. Thêm trigger phrase cụ thể, từ khoá kỹ thuật, file type liên quan.
- Hỏi Claude _"When would you use the \[skill name\] skill?"_ và sửa từ chỗ Claude trả lời thiếu.

**Overtriggering** (load nhầm):

- Thêm **negative trigger**: _"Do NOT use for simple data exploration (use data-viz skill instead)."_
- Specific hơn: thay _"Processes documents"_ bằng _"Processes PDF legal documents for contract review"_.
- Làm rõ scope: _"Use specifically for online payment workflows, not for general financial queries."_

## Khi instruction load mà Claude không follow

Thường rơi vào một trong bốn:

- **Dài dòng quá** — cắt gọn, dùng bullet, đẩy detail sang `references/`.
- **Không đưa thông tin quan trọng lên đầu** — chuyển hướng dẫn quan trọng lên đầu, nhắc lại nếu cần.
- **Mơ hồ** — _"Make sure to validate things properly"_ → _"CRITICAL: verify project name is non-empty, at least one team member assigned, start date not in the past."_
- **Lười** (đặc biệt với task dài) — thêm _"Take your time. Quality is more important than speed. Do not skip validation steps."_ Thường hiệu quả hơn khi đặt trong user prompt thay vì SKILL.md.

Vấn đề về context: nếu skill chậm hoặc response sa sút — `SKILL.md` quá lớn (chuyển sang `references/`), bật quá nhiều skill cùng lúc (Anthropic gợi ý không quá 20-50), hoặc không dùng progressive disclosure.

## Chia sẻ skill thế nào?

Tháng 1/2026, có ba con đường:

- **Cá nhân** — download folder, zip, upload vào Claude.ai (Settings > Capabilities > Skills) hoặc đặt vào skills directory của Claude Code.
- **Tổ chức** — admin deploy workspace-wide qua Claude Console, auto update, quản lý tập trung (ship 18/12/2025).
- **API / programmatic** — endpoint `/v1/skills` để list & manage, thêm skill vào Messages API qua `container.skills`. Cần Code Execution Tool beta. Phù hợp khi build app, agent, hoặc pipeline tự động.

Approach khuyến nghị: **host trên GitHub repo public**, kèm README cấp repo cho người đọc (không phải bên trong skill folder), example sử dụng có screenshot, và link từ doc của MCP server (nếu có). Khi viết về skill — focus vào **outcome, không phải feature**.

Skill là một _open standard_ giống MCP — Anthropic muốn skill portable giữa các nền tảng AI khác nhau. Nếu skill phụ thuộc capability đặc thù của Claude, ghi rõ trong field `compatibility`.

## Checklist trước khi upload

```
[ ] Folder name kebab-case, không space/capital
[ ] File tên đúng SKILL.md (case-sensitive)
[ ] Frontmatter có --- ở đầu và cuối
[ ] name: kebab-case, không capital
[ ] description: có cả WHAT và WHEN, < 1024 ký tự
[ ] Không có XML tag (< >) trong frontmatter
[ ] Instructions rõ ràng, có ví dụ
[ ] Có troubleshooting section
[ ] Reference link tới references/ rõ ràng
[ ] Không có README.md trong skill folder
[ ] Đã test trigger trên prompt obvious + paraphrased
[ ] Đã test không trigger trên prompt unrelated
[ ] Functional test pass
```

## Tài liệu chính thức

- Skills documentation: [docs.claude.com/en/docs/agents-and-tools/skills](https://docs.claude.com/en/docs/agents-and-tools/skills)
- Best Practices Guide: [anthropic.com/engineering](https://www.anthropic.com/engineering)
- Public skills repo: [github.com/anthropics/skills](https://github.com/anthropics/skills)
- skill-creator skill — tích hợp sẵn trong Claude.ai và Claude Code
- MCP: [modelcontextprotocol.io](https://modelcontextprotocol.io)

Nguồn: _The Complete Guide to Building Skills for Claude_ — Anthropic.

According to Anthropic, **a skill is a set of instructions — packaged as a simple folder — that teaches Claude how to handle a specific task or workflow**. Instead of repeating preferences and processes in every conversation, skills let you _teach Claude once and reuse forever_.

> "A skill is a set of instructions — packaged as a simple folder — that teaches Claude how to handle specific tasks or workflows."

> — Anthropic, _The Complete Guide to Building Skills for Claude_

Skills shine when you have **repeatable workflows**: generating frontend from a spec in a consistent style, writing research with the same methodology, producing docs to a team style guide, or orchestrating multi-step processes across MCPs.

This post is a practical condensation of the official guide — enough to ship a working skill in 15–30 minutes.

## What a skill is — structurally

A skill is a folder containing:

- **\`SKILL.md\`** _(required)_ — Markdown with YAML frontmatter at the top.
- **\`scripts/\`** _(optional)_ — executable code (Python, Bash, …).
- **\`references/\`** _(optional)_ — detailed docs, loaded on demand.
- **\`assets/\`** _(optional)_ — templates, fonts, icons used in output.

The folder name must be **kebab-case** (e.g. `notion-project-setup`). No spaces, no underscores, no capitals. The file **must** be exactly `SKILL.md` (case-sensitive). And **no \`README.md\`** inside the skill folder — repo-level READMEs are for human readers, not Claude.

## Progressive disclosure — why skills differ from CLAUDE.md

Skills use a three-level system:

1. **YAML frontmatter** — always in Claude's system prompt. Just enough for Claude to decide _whether_ a skill is relevant, without loading the whole thing.
1. **\`SKILL.md\` body** — loaded when Claude judges the skill relevant. Full instructions live here.
1. **Linked files** (`references/`, `scripts/`, …) — Claude navigates to them as needed.

The key difference vs. `CLAUDE.md`: `CLAUDE.md` loads **every session**. A skill loads **on demand**. If you have 30 domain-specific procedures, dumping them into `CLAUDE.md` bloats context and Claude starts ignoring instructions — _"Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"_ Splitting into skills is the fix.

## When to build a skill

Anthropic identifies three common categories:

- **Document & asset creation** — consistent output: docx, pptx, xlsx, frontend design, components matching a style guide. Embed brand standards, templates, quality checklists. No MCP needed.
- **Workflow automation** — multi-step processes that benefit from a consistent methodology, validation gates, and refinement loops. The skill-creator skill itself is the canonical example.
- **MCP enhancement** — you already have an MCP server; the skill is the _knowledge layer_ on top: how to use the MCP with the right workflow, in the right order, with proper error handling.

If you're shipping an MCP server, a skill turns raw tool access into a reliable workflow. Anthropic's analogy: **MCP is the professional kitchen (tools, ingredients). Skills are the recipes (how to use them to make something valuable).**

## YAML frontmatter — the most important part

This is the only thing Claude **always** reads when deciding whether to load your skill. Minimum format:

```yaml
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---
```

Rules for `description`:

- **Must include both**: what the skill _does_ + _when to use it_ (trigger conditions).
- Under 1024 characters, no XML tags (`<` `>`).
- Spell out specific phrases users might say.
- Mention file types if relevant.

Good example:

```yaml
description: >
  Manages Linear project workflows including sprint planning,
  task creation, and status tracking. Use when user mentions
  "sprint", "Linear tasks", "project planning", or asks to
  "create tickets".
```

Bad — Claude will never trigger:

```yaml
description: Helps with projects.                                  # too vague
description: Creates sophisticated multi-page documentation systems.  # missing triggers
```

Debugging tip: ask Claude _"When would you use the \[skill name\] skill?"_ — it'll quote the description back to you. Read the answer to see what's missing.

**Forbidden in frontmatter**: XML angle brackets (`<` `>`), and skill names containing `"claude"` or `"anthropic"` (reserved). Frontmatter ends up in the system prompt, so it's restricted to prevent prompt injection.

## Body of SKILL.md

After the frontmatter, write Markdown. Anthropic's recommended template:

```markdown
# Your Skill Name

## Instructions

### Step 1: [first major step]
Clear explanation of what happens.

Example:
```

python scripts/fetch_data.py --project-id PROJECT_ID

```
Expected output: [describe what success looks like]

## Examples

### Example 1: [common scenario]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link

## Troubleshooting

### Error: [common error message]
Cause: [why it happens]
Solution: [how to fix]
```

Writing principles:

- **Specific & actionable** — _"Run \`python scripts/validate.py --input {filename}\` to check data format"_ beats _"Validate the data before proceeding"_.
- **Reference clearly** — _"Before writing queries, consult \`references/api-patterns.md\` for rate limiting, pagination, and error codes."_
- **Keep \`SKILL.md\` short** — under ~5,000 words. Move detailed docs into `references/`.
- **Critical instructions go at the top** — Claude reads in order; don't bury them.
- **Be unambiguous** — _"CRITICAL: Before calling create_project, verify name is non-empty"_ beats _"Make sure to validate things properly"\_.

For _truly_ critical validation, don't rely on language — _"Code is deterministic; language interpretation isn't."_ Bundle a script and call it from the instructions.

## Five patterns that work

Not prescriptive templates — patterns the community has used successfully:

1. **Sequential workflow orchestration** — multi-step workflows in a strict order, with dependencies between steps and rollback paths. Example: customer onboarding (create account → setup payment → create subscription → send welcome email).
1. **Multi-MCP coordination** — a workflow that spans multiple MCP servers. Example design-to-dev: Figma MCP exports assets → Drive MCP stores them → Linear MCP creates tasks → Slack MCP posts the handoff. Needs explicit data passing between phases.
1. **Iterative refinement** — output improves with iteration. Initial draft → quality check (run a validation script) → refinement loop → finalize. The two essentials: **explicit quality criteria** and **knowing when to stop**.
1. **Context-aware tool selection** — same outcome, different tools depending on context. Smart file storage: large file → cloud MCP, collaborative doc → Notion, code → GitHub, temp → local. Make the decision tree transparent.
1. **Domain-specific intelligence** — the skill carries expertise beyond tool access. Payment with compliance: check sanctions lists → assess risk → process or flag → log audit trail.

A framing question: is your skill **problem-first** ("I need to set up a workspace" → the skill picks the tools) or **tool-first** ("I have Notion MCP connected" → the skill teaches the optimal workflow)? Most skills lean one way. Knowing which helps you pick the pattern.

## Testing — three layers

Anthropic's recommended order:

### 1. Triggering tests

Skill loads when it should, doesn't load when it shouldn't.

```
Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (unless your skill handles sheets)
```

Target: trigger on ~90% of relevant queries, near zero on irrelevant ones.

### 2. Functional tests

Run the workflow → check the output. Example: "Create project with 5 tasks" → project created, 5 tasks with correct properties, all linked to the project, no API errors.

### 3. Performance comparison

Vs. baseline without the skill:

```
Without skill:                With skill:
- 15 back-and-forth msgs      - Automatic workflow
- 3 failed API calls          - 2 clarifying questions only
- 12,000 tokens               - 0 failed API calls
                              - 6,000 tokens
```

**Pro tip from Anthropic**: iterate on **one** hard task until Claude succeeds, _then_ extract the winning approach into a skill. Fastest signal, leverages in-context learning. Only after that, expand to broader test coverage.

## When the skill doesn't trigger (or triggers wrong)

**Under-triggering** (doesn't load when it should):

- Description too vague. Add specific trigger phrases, technical keywords, relevant file types.
- Ask Claude _"When would you use the \[skill name\] skill?"_ and edit based on whatever's missing in the answer.

**Over-triggering** (loads on irrelevant queries):

- Add **negative triggers**: _"Do NOT use for simple data exploration (use data-viz skill instead)."_
- Be more specific: replace _"Processes documents"_ with _"Processes PDF legal documents for contract review"_.
- Clarify scope: _"Use specifically for online payment workflows, not for general financial queries."_

## When instructions load but Claude doesn't follow them

Usually one of four causes:

- **Too verbose** — trim, use bullets and numbered lists, push detail into `references/`.
- **Buried** — move critical instructions to the top, repeat key points if needed.
- **Ambiguous language** — _"Make sure to validate things properly"_ → _"CRITICAL: verify project name is non-empty, at least one team member assigned, start date not in the past."_
- **Model laziness** (especially on long tasks) — add _"Take your time. Quality is more important than speed. Do not skip validation steps."_ Often more effective in the user prompt than in `SKILL.md`.

If the skill feels slow or output quality drops: `SKILL.md` is too large (move detail to `references/`), too many skills enabled at once (Anthropic suggests not more than 20–50), or you're not using progressive disclosure.

## Distributing your skill

As of January 2026, three paths:

- **Individuals** — download the folder, zip it, upload via Claude.ai (Settings > Capabilities > Skills), or place it in the Claude Code skills directory.
- **Organizations** — admins deploy skills workspace-wide via the Claude Console, with automatic updates and centralized management (shipped 2025-12-18).
- **API / programmatic** — `/v1/skills` to list and manage, then add skills to Messages API requests via `container.skills`. Requires the Code Execution Tool beta. Right for apps, agents, and automated pipelines.

Recommended approach: **host on a public GitHub repo**, with a repo-level README for human readers (not inside the skill folder), example usage with screenshots, and a link from your MCP server's docs if you have one. When you describe the skill, **focus on outcomes, not features**.

Skills are an _open standard_, like MCP — Anthropic wants them portable across AI platforms. If a skill leans on Claude-specific capabilities, note that in the `compatibility` field.

## Pre-upload checklist

```
[ ] Folder name kebab-case, no spaces or capitals
[ ] File named exactly SKILL.md (case-sensitive)
[ ] Frontmatter has --- delimiters at top and bottom
[ ] name: kebab-case, no capitals
[ ] description: includes WHAT and WHEN, under 1024 chars
[ ] No XML tags (< >) anywhere in frontmatter
[ ] Instructions are clear with examples
[ ] Troubleshooting section present
[ ] Reference links to references/ are explicit
[ ] No README.md inside the skill folder
[ ] Triggering tested on obvious + paraphrased prompts
[ ] Verified it doesn't trigger on unrelated prompts
[ ] Functional tests pass
```

## Official sources

- Skills documentation: [docs.claude.com/en/docs/agents-and-tools/skills](https://docs.claude.com/en/docs/agents-and-tools/skills)
- Best Practices Guide: [anthropic.com/engineering](https://www.anthropic.com/engineering)
- Public skills repository: [github.com/anthropics/skills](https://github.com/anthropics/skills)
- skill-creator skill — built into Claude.ai and Claude Code
- MCP: [modelcontextprotocol.io](https://modelcontextprotocol.io)

Source: _The Complete Guide to Building Skills for Claude_ — Anthropic.