15.3 · Cấu hình & skill nhiều file

Mở đầu: Từ skill 20 dòng sang skill 2000 dòng

Tình huống của Linh — Content Marketer

Linh build skill blog-post-writer cho team. Version đầu, cô gom tất cả vào 1 file:

~/.claude/skills/blog-post-writer/
└── SKILL.md   ← 1800 dòng!
     ├── Brand voice guidelines (extracted từ PDF 40 trang)
     ├── SEO checklist (27 điểm)
     ├── Past examples (5 bài blog cũ làm reference)
     ├── CTA templates (12 loại)
     ├── Social teaser patterns
     ├── Meta description rules
     └── Internal linking strategy

Test skill: work rất tốt. Nhưng sau 2 tuần:

• Mỗi lần skill trigger → ăn 30% context window chỉ riêng skill này
• Khi Linh cần làm việc khác sau khi viết blog (ví dụ, review PR): context đã bị skill blog chiếm, Claude "lú"
• Team muốn update brand voice (1 dòng): phải mở file 1800 dòng tìm đoạn → sửa → rất dễ sai

Đây là lý do có progressive disclosure + multi-file.

Otto ví von: "It's like having a table of contents in the context window rather than fitting the whole document in there."

4 metadata field — full spec

Bài 15.1 và 15.3 bạn đã biết 2 field bắt buộc. Bài này complete bức tranh.

Ví dụ skill dùng cả 4:

---
name: codebase-onboarding
description: Helps new developers understand how the system works. Use when onboarding a new team member, explaining architecture, or giving a codebase tour.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

Field 1: name

• Lowercase, số, dấu gạch ngang (-) only
• Max 64 chars
• Phải khớp tên folder
• Không underscore, không space, không uppercase

Field 2: description — Quan trọng nhất

Max 1024 chars. Nhưng bạn không nên dùng hết. 150-300 chars là sweet spot.

Tại sao quan trọng nhất? Vì Claude dùng chỉ description để quyết định có trigger skill hay không. Code bạn viết, tool bạn config — không matter nếu description không match.

Chi tiết cách viết ở phần "Writing Effective Descriptions" dưới đây.

Field 3: allowed-tools — Guardrail bảo mật

Khi skill active, Claude chỉ được dùng tools liệt kê trong field này. Không có Edit, không có Write, không Bash → skill không thể modify gì cả.

Format: comma-separated list tên tool.

allowed-tools: Read, Grep, Glob, Bash

Tool name phải đúng (Case-sensitive):

• Read, Write, Edit — file operations
• Grep, Glob — search
• Bash — shell command
• WebFetch, WebSearch — internet access
• ... (xem docs Claude Code cho full list)

Nếu omit field này: Claude dùng permission model bình thường (bạn vẫn được hỏi trước mỗi tool call risky).

Field 4: model — Chọn Claude model

Specify model chạy skill:

model: sonnet       # default, balanced
model: opus         # slower, more capable
model: haiku        # fastest, simple tasks

Khi nào dùng?

• haiku cho skill lặp đi lặp lại, simple (format commit, extract field từ text)
• sonnet cho hầu hết case (default, good balance)
• opus cho skill cần reasoning sâu (code review complex, architectural decision)

Trade-off: model mạnh hơn → chậm hơn + tốn tiền hơn. Đừng dùng opus cho task format đơn giản.

Writing Effective Descriptions — Công thức

Nguyên tắc: Description phải trả lời 2 câu hỏi

1. Skill này làm gì? (action cụ thể)
2. Khi nào Claude nên dùng? (trigger phrases)

Nếu Otto đưa bạn job description: "Your job is to help with docs" — bạn không biết nên làm gì. Claude cũng vậy.

Công thức 3 phần

[Action verb + object] + [use case] + [trigger phrases]

Ví dụ tiến hóa của 1 description

V1 — ❌ Quá chung:

Helps with code.

Problem: Match hầu như mọi câu hỏi coding. Claude trigger quá nhiều.

V2 — ⚠️ Đã rõ hơn nhưng thiếu trigger:

Reviews pull requests for code quality.

Problem: User nói "check my changes" hoặc "give PR feedback" — không có từ "review" hay "pull request" → miss.

V3 — ✅ Đủ:

Reviews pull requests for code quality, checking typing, tests, and security. Use when asked to review a PR, check my changes, give PR feedback, or examine a branch before merge.

Phân tích V3:

• Action: "Reviews pull requests for code quality, checking typing, tests, security"
• Use case nuanced: biết skill check gì (typing, tests, security)
• 4 trigger phrases: cover cách diễn đạt khác nhau user thực tế dùng

Test trigger phrases

Trước khi finalize description, viết 5 câu user có thể gõ để trigger skill:

Nếu variation fail → thêm keyword vào description. Trong case này, thêm "examine a diff" hoặc "look at code changes".

Litton's tip (AI University)

In order to trigger a specific task related to that skill you need to provide a concrete trigger word or magic word. In my case my trigger word would be 'email personalization'.

Cách reliable nhất: có 1 trigger phrase "magic" user memorize, đồng thời cover các variation khác. Ví dụ:

• Magic: "review this PR"
• Variations: "check my changes", "give PR feedback", "examine branch"

allowed-tools — Deep dive

Tại sao cần tool restriction?

3 scenario thực tế:

Scenario 1: Read-only audit skill

Bạn build skill security-audit — Claude scan code tìm lỗ hổng. Không được sửa gì (để team review manual). Nếu skill không restrict, Claude có thể "chủ động" sửa — risky.

allowed-tools: Read, Grep, Glob

Không có Edit, Write, Bash → Claude chỉ đọc, không thể touch file.

Scenario 2: Compliance workflow

Finance team có skill monthly-reconcile. Output phải là Excel file mới, không được sửa source files (bank statement, invoice log).

allowed-tools: Read, Grep, Write, Bash

Có Write để tạo file mới, nhưng không có Edit để modify file hiện có.

Scenario 3: Onboarding skill cho new hire

Skill codebase-tour giúp intern hiểu project. Không cho intern vô tình run bash làm hư repo:

allowed-tools: Read, Grep, Glob

Bỏ Bash hoàn toàn.

Skill codebase-onboarding — complete example

---
name: codebase-onboarding
description: Helps new developers understand how this codebase works. Use when onboarding, explaining architecture, or giving a codebase tour to someone new.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

When a new developer asks to understand this codebase:

1. Start with project structure:
   - Run `tree -L 2 -I 'node_modules|.next|dist'`
   - Identify main directories (src/, lib/, app/, etc.)

2. Walk through key files:
   - Read package.json → explain dependencies + scripts
   - Read src/index.ts (or equivalent entry point)
   - Read README.md if exists

3. Explain the architecture:
   - Identify framework (Next.js, Express, FastAPI, etc.)
   - Explain data flow (where does a request go?)
   - Point to config files (env, database, auth)

4. Suggest 3 beginner-friendly issues:
   - Use grep to find TODO comments
   - Suggest typing improvements
   - Doc updates

Tone: welcoming, patient. This person is new. Avoid jargon unless explained.

Omit allowed-tools — nghĩa là gì?

---
name: my-skill
description: ...
---

Khi skill này active, Claude dùng permission model bình thường: bạn vẫn phải approve mỗi tool call risky (Write, Edit, Bash), nhưng Claude không bị restrict về loại tool.

→ Phù hợp cho skill "general-purpose". Không nên dùng allowed-tools nếu không có lý do cụ thể, vì nó cản Claude dùng tool hữu ích.

Progressive Disclosure — Cốt lõi của multi-file skill

Vấn đề: context window hữu hạn

Mỗi conversation Claude có context window hữu hạn (ví dụ 200K token, 1M token tùy model). Tất cả — system prompt + skill metadata + user messages + tool results + skill content khi active — share cùng 1 ngân sách.

Nếu skill của bạn = 2000 dòng ~50K token, mỗi lần active → 25% context đi tong cho content có thể bạn chỉ cần 10%.

Solution: chia SKILL.md thành core + reference

my-skill/
├── SKILL.md                        ← core instructions (< 500 dòng)
│                                     Load khi skill active
├── references/                     ← chi tiết
│   ├── full-brand-voice.md         ← Load khi task cần brand voice
│   ├── seo-deep-dive.md            ← Load khi task cần SEO
│   └── past-examples.md            ← Load khi cần example
├── scripts/                        ← executable
│   └── check-grammar.py            ← Run, không load content
└── assets/                         ← static
    ├── template.md
    └── logo.png

Trong SKILL.md, link tới file phụ với rõ context khi nào load:

---
name: blog-post-writer
description: Writes blog posts following brand and SEO guidelines. Use when writing a blog post, article, or long-form content.
---

When writing a blog post:

1. Understand the topic + target audience
2. Create outline (see references/outline-pattern.md for full template)
3. Write draft following brand voice:
   - Short summary here (3 lines)
   - For deep guidance on tone/style, read references/full-brand-voice.md
4. Apply SEO (see references/seo-deep-dive.md for 27-point checklist)
5. Before submitting, run scripts/check-grammar.py on the draft

Example past posts: references/past-examples.md

Claude decision flow

User: "Write a blog post about AI skills"
         ↓
Claude matches skill blog-post-writer
         ↓
Confirmation → loads SKILL.md (~400 dòng)
         ↓
Claude reads: "Apply brand voice..."
         ↓
Does current task need deep brand guidance?
    YES → Claude reads references/full-brand-voice.md
    NO  → Claude skips it
         ↓
Continues with SEO step...
    Does task need deep SEO? → Read if yes
         ↓
Run scripts/check-grammar.py on draft
    (Claude executes, doesn't load content)
         ↓
Final output

Kết quả: Mỗi conversation chỉ load subset skill cần thiết. Phần còn lại "ngủ" trên disk, không ăn context.

Quy tắc vàng: SKILL.md < 500 dòng

Otto set con số cụ thể. Nếu SKILL.md > 500 dòng → nghĩ lại:

• Có phần nào thành reference riêng được?
• Có instruction nào chỉ cần đôi khi?
• Có example có thể move sang references/past-examples.md?

3 subfolder chuẩn: references/, scripts/, assets/

Agent skills open standard (agentskills.io) define 3 subfolder với vai trò rõ:

references/ — documentation phụ

File .md chứa chi tiết Claude đọc khi cần. Ví dụ:

blog-post-writer/
└── references/
    ├── brand-voice.md          ← tone, từ cấm, phong cách
    ├── seo-checklist.md        ← 27-point checklist
    ├── past-examples.md        ← 5 bài blog mẫu
    └── target-personas.md      ← Sarah, Marcus, Linh personas

Link từ SKILL.md:

For deep guidance on tone, read references/brand-voice.md

Claude sẽ dùng Read tool để đọc file đó chỉ khi task của nó cần brand voice.

scripts/ — executable code

File code (.py, .sh, .js...) Claude run thay vì read. Đây là điểm đột phá cho skill.

Ví dụ: scripts/check-grammar.py — 200 dòng Python check ngữ pháp.

Trong SKILL.md:

Before submitting, run scripts/check-grammar.py on the draft:

    python scripts/check-grammar.py <draft-file.md>

The script returns a list of issues; fix them before submitting.

Claude sẽ:

• Không đọc content của check-grammar.py (tiết kiệm context)
• Run script qua Bash tool
• Chỉ output (stdout) consume tokens

Khi nào dùng script?

• Environment validation (check node version, env variable có đủ)
• Data transformation consistent (parse CSV, generate report)
• Operations reliability hơn khi là code (regex phức tạp, API call, file processing)
• Calculations chính xác (generate số, không để LLM tự tính)

Litton (DBS) ví dụ: "Step one, create the post. Step two, use the nano banana Python script in order to create an AI image." — Claude không tự generate image được, nên script gọi API Replicate/Midjourney.

assets/ — static files

Files không phải instruction, không executable — mà là material:

blog-post-writer/
└── assets/
    ├── template.md              ← blog post template có placeholder
    ├── company-logo.png         ← hình Claude attach vào output
    └── example-output.pdf       ← sample PDF format

Thường là template, image, sample data để Claude reference hoặc inject vào output.

Full example: skill gamma-present (từ DBS tutorial)

Đây là skill thật DBS build trong tutorial, minimal nhưng đầy đủ cấu trúc.

gamma-present/
├── SKILL.md                       ← 5-step workflow
└── references/
    ├── slide-structure.md         ← cách layout slide
    ├── storytelling-guide.md      ← narrative flow
    └── brand-guide.md             ← extracted từ 40-page PDF

Notice

Không có scripts/ vì "everything is taking place within the Gamma connector" (tất cả output qua MCP connector, không cần script). Không có assets/ vì skill không cần static file.

Nguyên tắc

Chỉ thêm subfolder khi thực sự cần. Đừng tạo scripts/ chỉ vì "standard có". Litton (DBS): "Direction only. The skill doesn't need blueprints because there's no proprietary business knowledge Claude needs, and it doesn't need solution scripts because the output is text in chat."

Case studies theo ngành

Legal — contract-review với allowed-tools security

---
name: contract-review
description: Reviews contracts against company standard terms. Use when reviewing an NDA, service agreement, vendor contract, or any legal document.
allowed-tools: Read, Grep, Glob
model: opus
---

contract-review/
├── SKILL.md                        ← checklist + red flag patterns
├── references/
│   ├── standard-terms.md           ← template condition của công ty
│   ├── red-flag-patterns.md        ← các điều khoản nguy hiểm
│   └── jurisdiction-notes.md       ← note theo US, EU, VN
└── assets/
    └── review-template.md          ← output format

Điểm đáng chú ý:

• allowed-tools: Read, Grep, Glob — Claude không thể edit contract
• model: opus — nghiệp vụ legal cần reasoning sâu, trade cost
• references/ tách 3 topic → chỉ load "jurisdiction-notes" khi contract là EU

Finance — monthly-close với scripts

---
name: monthly-close
description: Runs monthly close reconciliation. Use when asked to reconcile bank statement, match invoices, or run monthly close.
allowed-tools: Read, Write, Bash
---

monthly-close/
├── SKILL.md                        ← orchestration
├── scripts/
│   ├── match_transactions.py       ← fuzzy match amounts + dates
│   ├── variance_report.py          ← flag > $5K variance
│   └── export_excel.py             ← generate 3-sheet Excel
├── references/
│   └── variance-thresholds.md      ← rule flag theo department
└── assets/
    └── excel-template.xlsx

Điểm đáng chú ý:

• 3 script Python handle heavy lifting — Claude không "imagine" logic
• Template Excel có sẵn trong assets → consistent format
• allowed-tools không có Edit → không sửa source bank statement

Marketing — campaign-brief-generator

---
name: campaign-brief-generator
description: Generates marketing campaign briefs from product info. Use when creating a campaign brief, planning a campaign, or starting marketing work for a new feature.
---

campaign-brief-generator/
├── SKILL.md
├── references/
│   ├── brand-voice.md
│   ├── channel-playbook.md         ← LinkedIn vs Twitter vs Email
│   └── past-campaigns.md           ← 10 brief gần nhất
└── assets/
    └── brief-template.md

Không có scripts/: Claude tự viết content, không cần script. Không có allowed-tools restriction: Claude cần tạo file brief mới.

Engineering — deploy-checklist multi-env

---
name: deploy-checklist
description: Runs pre-deploy checklist for production. Use before deploying, before release, or when asked to verify ready for prod.
allowed-tools: Read, Grep, Bash
---

deploy-checklist/
├── SKILL.md
├── scripts/
│   ├── check_env_vars.sh           ← verify secret present
│   ├── run_smoke_tests.sh          ← health check
│   └── verify_db_migrations.py
└── references/
    ├── rollback-procedure.md       ← chỉ load nếu check fail
    └── incident-playbook.md

Clever bit: rollback-procedure.md và incident-playbook.md chỉ load khi bước kiểm tra fail. Không fail → không consume context.

Anti-patterns

Nhồi tất cả vào SKILL.md

Triệu chứng

SKILL.md 1500+ dòng, nửa là example/reference material.

Tại sao tệ

Mỗi lần skill active → ăn toàn bộ. Không tận dụng progressive disclosure. Maintain khổ.

Cách đúng

SKILL.md < 500 dòng, split còn lại vào references/.

allowed-tools quá strict

Triệu chứng

allowed-tools: Read → skill không tạo được output file.

Tại sao tệ

Skill không complete được task, user frustrated.

Cách đúng

List tối thiểu đủ tool. Audit skill → chỉ có Read. Skill tạo file → cần Write. Skill run script → cần Bash.

model: opus cho mọi skill

Triệu chứng

Mọi skill set model: opus "cho chắc".

Tại sao tệ

Opus chậm + đắt. Task đơn giản (format commit, extract field) chạy Haiku đủ.

Cách đúng:

• Simple repetitive → haiku
• General → sonnet (hoặc omit, default)
• Complex reasoning → opus

Đặt executable script trong references/

Triệu chứng

references/do-thing.py với expectation Claude read content để "learn".

Tại sao tệ

Claude sẽ đọc file (vì nằm trong references/), load vào context. Nếu script 500 dòng → ăn context. Đồng thời, Claude có thể cố "simulate" logic thay vì chạy thực.

Cách đúng

Script = scripts/. SKILL.md explicit nói "run this script" (không "read"). Otto: "Tell Claude to run the script, not read it."

Description phình to liệt kê mọi use case

Triệu chứng

description 900 chars mô tả skill có thể làm 15 việc.

Tại sao tệ

Overhead startup. Matching bớt chính xác (quá rộng).

Cách đúng

1 skill = 1 chức năng rõ. Nếu skill đang làm 15 việc → split thành 3-5 skill.

Áp dụng ngay

Bài tập 1: Nâng cấp skill của bạn lên multi-file (~15 phút)

Lấy skill bạn viết ở Bài 15.2 (Bài tập 2). Làm tiếp:

Bước 1: Identify điều gì trong SKILL.md có thể tách ra:

• Example/past cases → references/examples.md
• Checklist dài > 10 items → references/checklist.md
• Template format → assets/template.md

Bước 2: Tạo subfolder + di chuyển content:

cd ~/.claude/skills/<tên-skill>
mkdir references assets
mv long-checklist-content.md references/checklist.md

Bước 3: Cập nhật SKILL.md, link tới file phụ:

For the full checklist, read references/checklist.md
Use the output template in assets/template.md

Bước 4

Restart Claude Code + test. Skill vẫn work?

Bước 5

So sánh số dòng SKILL.md trước/sau:

• Trước: _____ dòng
• Sau: _____ dòng
• Giảm bao nhiêu %: _____

Bài tập 2: Thêm allowed-tools cho 1 skill (~5 phút)

Tự quyết định: skill nào nên read-only cho security/consistency?

Candidate:

• Bất kỳ skill review/audit (code review, contract review, security audit)
• Skill explanation/tutorial (không được modify code của learner)
• Skill documentation extraction

Thêm allowed-tools: Read, Grep, Glob vào frontmatter của skill đó. Test → Claude có complete task không? Nếu cần Write (ví dụ tạo report), thêm Write vào list.

Tóm tắt bài học

Tài liệu tham khảo

• Anthropic Academy — "Configuration and multi-file skills"
• Video — "Advanced skill configuration"
• agentskills.io — full field spec
• DBS Tutorial — "Direction / Blueprints / Solutions" framework (YouTube)