Research: Claude Skill Creator — Tổng hợp nguồn chính thức

Mục đích: Tài liệu nghiên cứu gốc phục vụ bài học 15_Skills.md và bộ 18 gói kỹ năng nội bộ trong Skills/vagataba-*/SKILL.md. Ngày nghiên cứu gốc: 12/05/2026 (Cập nhật bổ sung mốc nền tảng 08–10/2026: 20/10/2026) Nguồn: agentskills.io (Anthropic), Claude Platform Docs (platform.claude.com), Anthropic Engineering Blog, cộng đồng

1. Agent Skills Specification (agentskills.io)

1.1 Cấu trúc thư mục

skill-name/
├── SKILL.md      # Required: metadata + instructions
├── scripts/      # Optional: executable code
├── references/   # Optional: documentation
├── assets/       # Optional: templates, resources
└── ...           # Any additional files or directories

1.2 YAML Frontmatter — 6 fields

Phát hiện mới: Spec chính thức có thêm license, compatibility, metadata, allowed-tools — skill-creator V3.0.1 chưa cover.

1.3 Progressive Disclosure — 3 tầng token budget

Tầng 1 — Metadata (~100 tokens):
  name + description — loaded at startup cho MỌI skill đang bật.

Tầng 2 — Instructions (< 5000 tokens khuyến nghị):
  SKILL.md body — loaded khi skill activated.

Tầng 3 — Resources (as needed):
  scripts/, references/, assets/ — loaded only when required.

Phát hiện mới: Spec ghi rõ < 5000 tokens cho SKILL.md body. Skill-creator V3.0.1 chỉ nói "< 500 dòng" — cần bổ sung token budget.

1.4 Validation Tool

skills-ref validate ./my-skill

Dùng package skills-ref từ GitHub agentskills/agentskills để validate cấu trúc skill.

2. Best Practices (agentskills.io/skill-creation/best-practices)

2.1 Bắt đầu từ thực tế (Start from real expertise)

Extract from a hands-on task:

• Steps that worked — sequence of actions leading to success
• Corrections made — places where you steered the agent
• Input/output formats — data going in and coming out
• Context provided — project-specific facts the agent didn't know

Synthesize from existing artifacts:

• Internal documentation, runbooks, style guides
• API specifications, schemas, config files
• Code review comments, issue trackers
• Version control history, patches/fixes
• Real-world failure cases and resolutions

Insight: Skill nên được "extract" từ workflow thực tế đã thành công, không phải viết từ đầu. Skill-creator nên hướng dẫn cách extract.

2.2 Spending context wisely

"Add what the agent lacks, omit what it knows"

<!-- Quá dài — agent đã biết PDF là gì -->
## Extract PDF text
PDF (Portable Document Format) files are a common file format...

<!-- Tốt hơn — nhảy thẳng vào project-specific -->
## Extract PDF text
Use pdfplumber for text extraction.
For scanned documents, fall back to pdf2image with pytesseract.

"Design coherent units" — mỗi skill 1 chủ đề thống nhất.

"Aim for moderate detail" — không quá chi tiết, không quá chung.

2.3 Calibrating control

Match specificity to fragility:

• Quy trình an toàn → viết loose, cho agent linh hoạt
• Quy trình "giòn" (database migration) → viết chính xác từng lệnh, "Do not modify"

Provide defaults, not menus:

<!-- Sai: quá nhiều option -->
You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...

<!-- Đúng: 1 default + escape hatch -->
Use pdfplumber for text extraction.
For scanned PDFs requiring OCR, use pdf2image instead.

Insight mới cho skill-creator: Thêm nguyên tắc "defaults > menus" và "specificity ∝ fragility".

Favor procedures over declarations:

<!-- Sai: specific answer chỉ dùng 1 lần -->
Join `orders` to `customers` on `customer_id`, filter `region = 'EMEA'`...

<!-- Đúng: reusable method -->
1. Read schema from `references/schema.yaml`
2. Join tables using `_id` foreign key convention
3. Apply filters as WHERE clauses
4. Aggregate and format as markdown table

2.4 Patterns cho instructions hiệu quả

Gotchas sections — liệt kê "bẫy" mà agent sẽ gặp:

## Gotchas
- The `users` table uses soft deletes. MUST include `WHERE deleted_at IS NULL`.
- User ID = `user_id` in DB, `uid` in auth, `accountId` in billing. All same.
- `/health` returns 200 even if DB down. Use `/ready` instead.

Templates for output format — dùng concrete template thay vì mô tả trừu tượng:

## Report structure
Use this template:
# [Analysis Title]
## Executive summary
## Key findings
## Recommendations

Checklists for multi-step workflows:

## Form processing workflow
Progress:
- [ ] Step 1: Analyze form (run `scripts/analyze.py`)
- [ ] Step 2: Create field mapping
- [ ] Step 3: Validate mapping
- [ ] Step 4: Fill the form
- [ ] Step 5: Verify output

Validation loops:

1. Make edits
2. Run validation: `python scripts/validate.py output/`
3. If fails → fix → re-validate
4. Only proceed when validation passes

Plan-validate-execute — 3 bước tách rời: lập kế hoạch → validate → thực thi.

Insight mới cho skill-creator: Cần thêm 5 pattern này (Gotchas, Template, Checklist, Validation loop, Plan-validate-execute) vào hướng dẫn viết skill.

3. Optimizing Descriptions (agentskills.io/skill-creation/optimizing-descriptions)

3.1 Nguyên tắc viết description

1. Use imperative phrasing: "Use this skill when…" thay vì "This skill does…"
2. Focus on user intent, not implementation: Mô tả MỤC ĐÍCH user, không phải cơ chế nội bộ
3. Err on the side of being pushy: Liệt kê rõ context, kể cả khi user không gọi trực tiếp — "even if they don't explicitly mention 'CSV' or 'analysis'"
4. Keep it concise: Vài câu đến 1 đoạn ngắn. Hard limit 1024 chars

3.2 Quy trình tối ưu description (Eval-driven)

Thiết kế eval queries:

[
  {"query": "I've got a spreadsheet in ~/data/q4.xlsx...", "should_trigger": true},
  {"query": "whats the quickest way to convert json to yaml", "should_trigger": false}
]

Should-trigger queries — đa dạng:

• Phong cách: formal, casual, có typo
• Độ rõ: gọi tên domain trực tiếp vs. mô tả mơ hồ
• Chi tiết: ngắn vs. dài với file paths, column names
• Phức tạp: 1 bước vs. multi-step

Should-not-trigger queries — phải đủ khó:

• ❌ "Write a fibonacci function" — quá dễ, test nothing
• ✅ "Update formulas in my Excel budget" — gần gũi nhưng khác scope

3.3 The Optimization Loop

1. Evaluate trên train set (60%) + validation set (40%)
2. Identify failures trên train set
3. Revise description (generalise, KHÔNG overfit)
4. Repeat cho đến khi train pass
5. Chọn iteration có validation pass rate cao nhất

Nguyên tắc tránh overfitting:

• KHÔNG thêm keyword cụ thể từ failed query
• Thay vào đó, tìm general category mà query đại diện
• Nếu stuck → thử cấu trúc description khác (reframe)
• Luôn check ≤ 1024 chars (description dễ phình ra)

Phát hiện mới: Skill-creator cần hướng dẫn eval-driven description optimization thay vì chỉ checklist tĩnh.

4. Evaluating Skills (agentskills.io/skill-creation/evaluating-skills)

4.1 Test case structure

{
  "skill_name": "csv-analyzer",
  "evals": [
    {
      "id": 1,
      "prompt": "...",
      "expected_output": "...",
      "files": ["evals/files/data.csv"],
      "assertions": [
        "The output includes a bar chart image file",
        "Both axes are labeled"
      ]
    }
  ]
}

4.2 Eval workspace structure

skill-workspace/
└── iteration-1/
    ├── eval-test-name/
    │   ├── with_skill/
    │   │   ├── outputs/
    │   │   ├── timing.json    # {total_tokens, duration_ms}
    │   │   └── grading.json   # {assertions[], pass_rate}
    │   └── without_skill/
    │       └── ...
    └── benchmark.json         # Aggregated with/without delta

4.3 Writing assertions

Tốt: Cụ thể, có thể verify

• "The output file is valid JSON"
• "The chart has labeled axes"
• "The report includes at least 3 recommendations"

Tệ: Mơ hồ hoặc quá cứng

• "The output is good" — không grade được
• "Uses exactly phrase 'Total Revenue: $X'" — quá brittle

4.4 Grading principles

• Require concrete evidence cho PASS. Không benefit of the doubt.
• Review assertions — assertions always pass = không hữu ích, always fail = assertion hỏng.
• Study delta — assertions pass WITH skill but fail WITHOUT = nơi skill tạo giá trị.
• Check stddev — cao = flaky eval hoặc instruction mơ hồ.

4.5 Iteration loop

1. Give eval signals + current SKILL.md → LLM propose improvements
2. Review + apply changes
3. Rerun all test cases in iteration-<N+1>/
4. Grade + aggregate
5. Human review. Repeat.

Key insight for iteration:

• Generalise from feedback, không patch cụ thể
• Keep lean — fewer, better instructions > exhaustive rules
• Explain the why — "Do X because Y causes Z" > "ALWAYS do X, NEVER do Y"
• Bundle repeated work — nếu mọi test tự viết helper script → bundle vào scripts/

5. Anti-patterns tổng hợp (Community + Anthropic)

6. Composability & Multi-skill Coordination

• Multiple skills có thể invoked simultaneously cho complex task
• Coordination qua structured metadata + model reasoning
• Quản lý library lớn (50+ skills):
  • Feature-based directory: /modules/billing/skills/
  • Manifest file tại repo root — map skill names → paths
• Naming convention: gerund form (processing-pdfs), kebab-case, descriptive
• Cross-platform portable: agentskills.io open standard → Claude.ai, Claude Code, Cursor, Gemini CLI...

7. Version Control cho Skills

Git as Source of Truth:

• Skills = filesystem-based → native Git compatible
• Branching: feature branches cho skill mới/update
• Pull Requests: peer review trước deploy
• CI/CD: automated testing trước merge

Versioning strategy:

• Code + Scripts: track changes to executable logic
• Prompt Templates: version instructions cho behavioral consistency
• Data/Config: Git LFS hoặc DVC cho large assets
• Semantic versioning: MAJOR.MINOR.PATCH

8. So sánh Skill vs Alternatives

Quy tắc phân biệt: CLAUDE.md cho facts, Skills cho procedures, MCP cho actions.

9. Cập nhật Nền tảng Claude Skills & Hệ sinh thái (08–10/2026)

Để đảm bảo tài liệu nguồn khớp hoàn toàn với bài học 15_Skills.md, 17_Plugins_Extensions.md và bộ 18 Skills nội bộ V7.1, cần lưu ý các cột mốc chính thức sau của Anthropic:

1. GA (General Availability) từ 19/08/2026 & Mở cho mọi gói tài khoản:
   • Agent Skills và Files API đã chuyển sang trạng thái GA từ ngày 19/08/2026 trên API và toàn bộ nền tảng Claude.
   • Tính năng Skills hiện mở cho mọi gói tài khoản kể cả gói Free (Free, Pro, Max, Team, Enterprise), với điều kiện người dùng bật "Code execution and file creation" trong Settings > Capabilities.
2. Giao diện quản lý mới (Customize > Skills) & Phân phối tổ chức:
   • Trên giao diện claude.ai và Claude Desktop, người dùng quản lý kỹ năng tại mục Customize > Skills (thay cho đường dẫn cài đặt cũ).
   • Trên gói Team và Enterprise, Owner/Admin có thể xuất bản kỹ năng cho toàn tổ chức thông qua nút Publish to org.
3. Đồng bộ đa bề mặt (Cross-surface Sync):
   • Skills tải lên trên claude.ai được tự động đồng bộ sang Claude Code (v2.1.273+) và các tiện ích bổ trợ Claude cho Microsoft 365 (Excel, PowerPoint, Word) mà không cần cài đặt lại thủ công ở từng nơi.
4. Quét bảo mật tự động (Enterprise Skill & Plugin Security Scanning — 02/10/2026):
   • Từ ngày 02/10/2026, Anthropic bổ sung cơ chế quét bảo mật tự động đối với các Skill và Plugin do tổ chức tải lên nhằm phát hiện mã độc, hành vi đánh cắp dữ liệu (data exfiltration) hoặc chỉ dẫn ẩn (prompt injection).
5. Mối quan hệ giữa Skills và Plugins (17_Plugins_Extensions.md):
   • Skill (SKILL.md) đóng gói quy trình và tri thức chuyên môn theo chuẩn mở agentskills.io.
   • Plugin là gói đóng gói cấp cao hơn, kết hợp đồng bộ Skills + MCP Connectors + Sub-agents + Hooks / Slash commands để triển khai trọn bộ cho một vị trí hoặc phòng ban.

Nguồn tham khảo

Nghiên cứu phục vụ bài học 15_Skills.md và bộ 18 gói kỹ năng Skills/vagataba-*/SKILL.md (Chuẩn V7.1 — cập nhật 20/10/2026)