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

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:

Field 1: name

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.

• 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

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 3: allowed-tools — Guardrail bảo mật

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

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:

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

allowed-tools: Read, Grep, Glob, Bash

Field 4: model — Chọn Claude model

Khi nào dùng?

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.

• 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)

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

Writing Effective Descriptions — Công thức

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

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

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

V1 — ❌ Quá chung:

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

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

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

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:

Helps with code.

Writing Effective Descriptions — Công thức (tiếp)

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.

Writing Effective Descriptions — Công thức (tiếp)

Phân tích V3:

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)

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

• 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
• Magic: "review this PR"
• Variations: "check my changes", "give PR feedback", "examine branch"

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.

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.

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, Glob

Tại sao cần tool restriction?

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, Write, Bash

allowed-tools — Deep dive (tiếp)

Bỏ Bash hoàn toàn.

Skill codebase-onboarding — complete example

allowed-tools: Read, Grep, Glob

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

allowed-tools — Deep dive (tiếp)

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

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ì?

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.

name: my-skill
description: ...
# không có allowed-tools

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

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

Claude decision flow

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

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

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?

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

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ụ:

Link từ SKILL.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:

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

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

scripts/ — executable code

Claude sẽ:

Khi nào dùng script?

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:

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

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

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

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.

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.

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."

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

Case studies theo ngành

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

Điểm đáng chú ý:

💰 Finance — monthly-close với scripts

• 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

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

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

💰 Finance — monthly-close với scripts

Điểm đáng chú ý:

📣 Marketing — campaign-brief-generator

• 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

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

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

📣 Marketing — campaign-brief-generator

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

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

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.

🛠️ Engineering — deploy-checklist multi-env

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.

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

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

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:

❌ Đặ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.

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

Á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:

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

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

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

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

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

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:

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:

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.

• Trước: _____ dòng
• Sau: _____ dòng
• Giảm bao nhiêu %: _____
• 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

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

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

🎯 4 metadata field: name, description (bắt buộc), allowed-tools, model (optional). model: opus/sonnet/haiku trade-off speed ↔ capability.

🎯 Description công thức: Action verb + object + use case + 3-5 trigger phrases. Giữ 150-300 chars. Test với variation user thực tế nói.

🎯 allowed-tools là guardrail bảo mật. Read-only skill → Read, Grep, Glob. Skill tạo report → thêm Write. Omit field = dùng permission bình thường.

🎯 Progressive disclosure: SKILL.md < 500 dòng, chi tiết vào references/, script vào scripts/, static file vào assets/. Claude chỉ load khi cần.

🎯 Script: Claude RUN, không READ. Lệnh trong SKILL.md phải explicit "run scripts/xyz.py". Output consume tokens, content script không. Dùng script cho validation, data transform, API call, calculation.