┌─────────────────────────────────────────────┐
│ Level 1: Metadata (luôn được load)          │
│   - YAML Frontmatter (name + description)   │
│   - ~100 tokens/skill                       │
└─────────────────────────────────────────────┘
                ↓ (khi Claude detect skill phù hợp)
┌─────────────────────────────────────────────┐
│ Level 2: Instructions (khi triggered)       │
│   - SKILL.md body                           │
│   - Dưới 500 dòng / ~5k tokens              │
└─────────────────────────────────────────────┘
                ↓ (khi cần chi tiết)
┌─────────────────────────────────────────────┐
│ Level 3: Resources (on-demand)              │
│   - Scripts, templates, references          │
│   - Effectively unlimited                   │
└─────────────────────────────────────────────┘

my-skill/
└── SKILL.md          # Required, dưới 500 dòng

my-skill/
├── SKILL.md          # Instructions chính (required)
├── templates/        # Templates Claude fill in
│   └── output-format.md
├── examples/         # Example outputs minh hoạ format mong muốn
│   └── sample-output.md
├── references/       # Domain knowledge, specifications
│   └── api-spec.md
└── scripts/          # Scripts Claude execute được
    └── validate.sh

---
name: my-skill
description: What this skill does and when to use it
allowed-tools: Read, Grep, Glob
---

# My Skill Name

## Overview
Brief description of what this skill does and the problem it solves.

## When to Use
- Specific trigger scenarios
- What the user might say

## Steps
1. First action with specific tool references
2. Second action with expected format
3. Validation step

## Output Format
Describe the expected output structure.

## Error Handling
- If [tool] fails: [fallback action]
- If [data] is missing: [ask user or skip]

## Examples

### Good Output
[Show what success looks like]

### Common Mistakes
[Show what to avoid]

description: Helps with code              # Quá vague
description: Queries /api/v2/sprint endpoint with OAuth2 bearer token  # Quá technical
description: Assists with any development task  # Quá broad

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.

description: Generates weekly sprint reports by pulling data from Jira and GitHub. Use when user asks for sprint summary or weekly progress report.

Skill có side effects (deploy, commit, push, payment...)?
  → disable-model-invocation: true

Skill là background knowledge (system context, codebase facts)?
  → user-invocable: false

Skill read-only / phân tích / generate (review, analyze, doc)?
  → Mặc định (cả hai gọi được)

# Read-only analysis skill
allowed-tools: Read, Grep, Glob

# Scaffolding skill (cần ghi file)
allowed-tools: Read, Write, Bash(git *)

# Deployment skill (chỉ chạy bash)
allowed-tools: Bash

disable-model-invocation: true       # Chỉ user gọi
allowed-tools: Bash                  # Chỉ chạy bash

---
name: fix-issue
description: Fix a GitHub issue
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

---
name: migrate-component
description: Migrate component from one framework to another
---

Migrate component $0 from $1 to $2.

Steps:
1. Read $0
2. Convert $1 syntax to $2
3. Update tests

---
name: pr-summary
description: Summarize changes in a pull request
allowed-tools: Bash(git *)
---

## Context

- Current branch: !`git branch --show-current`
- Changes: !`git diff --stat HEAD`
- Recent commits: !`git log --oneline -10`

## Your task

Summarize the above changes into a PR description.

---
name: deep-research
description: Research a topic thoroughly across the codebase
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

mkdir -p ~/.claude/skills
cp -r my-skill ~/.claude/skills/
chmod +x ~/.claude/skills/my-skill/scripts/*.py

mkdir -p .claude/skills
cp -r my-skill .claude/skills/
chmod +x .claude/skills/my-skill/scripts/*.py

# Kiểm tra structure
ls -la ~/.claude/skills/my-skill/

# Trong Claude Code
/skills          # Liệt kê skills available

Session start
  ↓
Claude scan: ~/.claude/skills/, .claude/skills/, plugin skills, bundled
  ↓
Load Level 1 metadata (name + description) của TẤT CẢ skills
  ↓
User gửi message
  ↓
Claude check description nào match
  ↓
Match → bash đọc SKILL.md (Level 2) vào context
  ↓
SKILL.md reference file phụ?
  ↓ (yes)
Claude đọc file đó (Level 3, on-demand)
  ↓
SKILL.md có script execute?
  ↓ (yes)
Claude chạy script → chỉ output vào context, không phải code
  ↓
Claude execute task theo instructions
  ↓
Trả kết quả cho user

blog-post-writer/
├── SKILL.md
├── templates/
│   ├── frontmatter-template.md
│   └── post-skeleton.mdx
└── references/
    ├── style-guide.md
    └── seo-checklist.md

---
name: blog-post-writer
description: Generate a complete blog post with proper frontmatter, structured sections, and SEO optimization. Use when user asks to write, draft, or create a new blog post.
allowed-tools: Read, Write, Bash(ls *)
---

# Blog Post Writer

## When to Use
- User says: "viết bài về X", "draft a post on Y", "tạo blog post"
- User provides a topic, outline, or research notes

## Steps

1. **Understand the topic** — đọc thông tin user provide, hỏi nếu thiếu
2. **Generate frontmatter** dùng template `templates/frontmatter-template.md`:
   - `title`: ≤60 chars, có keyword chính
   - `slug`: kebab-case, không tiếng Việt có dấu
   - `date`: ISO 8601 (today)
   - `tags`: ≤5 tags lowercase
3. **Build outline** theo structure `templates/post-skeleton.mdx`:
   - Intro (hook + thesis)
   - 3-5 H2 sections với content
   - Code examples (nếu technical)
   - Conclusion với CTA
4. **Write draft** trong file `blog/<date>-<slug>.md`
5. **SEO check** dùng `references/seo-checklist.md`

## Output Format

File `.md` đầy đủ tại `blog/<date>-<slug>.md` + summary các SEO improvements suggested.

---
name: seo-optimizer
description: Analyze an existing blog post for SEO improvements. Check title length, meta description, heading hierarchy, keyword density, internal/external links, and image alt texts. Use when user asks to "check SEO", "optimize for SEO", or "improve search ranking" of a post.
allowed-tools: Read, Grep
---

# SEO Optimizer

## When to Use
- User: "check SEO bài này", "tối ưu SEO cho post X"
- After writing a draft, before publishing

## Steps

1. Read post file (path từ user hoặc $ARGUMENTS)
2. Extract frontmatter và analyze:
   - **Title**: 50-60 chars? Có keyword chính?
   - **Description**: 150-160 chars?
   - **Slug**: kebab-case? SEO-friendly?
3. Analyze content:
   - **H1/H2/H3 hierarchy**: chỉ 1 H1, H2 → H3 không skip
   - **Keyword density**: keyword chính xuất hiện 1-3% (không stuffing)
   - **Internal links**: ít nhất 1-2 link tới posts khác
   - **External links**: link tới authoritative source
   - **Image alt texts**: mỗi `<img>` và `![]()` có alt
4. Output báo cáo với:
   - Specific issues + line numbers
   - Recommended fixes
   - Priority (high/medium/low)

---
name: image-optimizer
description: Analyze blog images and recommend optimization (format conversion to WebP/AVIF, resize, compression, alt text suggestions). Use when user adds new images or asks to optimize images for blog.
allowed-tools: Read, Bash(file *), Bash(identify *), Bash(du *)
---

# Image Optimizer

## When to Use
- User: "tối ưu ảnh", "compress image", "convert to WebP"
- New image added to /public/images/

## Steps

1. Get image info: `file`, `identify` (ImageMagick), `du -h`
2. Recommendations:
   - **Format**: PNG/JPG → WebP/AVIF (80% smaller)
   - **Dimensions**: nếu >2000px width, resize cho responsive
   - **Compression**: cwebp -q 85 hoặc sharp library
   - **Loading**: srcset suggestions cho responsive
3. Generate alt text dựa trên context bài viết
4. Output commands cụ thể để chạy

---
name: publish-checklist
description: Run pre-publish checklist for blog post: lint, build, SEO check, broken links, preview deploy. ONLY run when user explicitly says "publish", "deploy post", or "ready to ship".
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *), Read
---

# Publish Checklist

## When to Use
**Only when user explicitly says publish/deploy.** Never auto-trigger.

## Steps

1. ✅ `npm run lint` — fix tất cả lint errors
2. ✅ `npm run build` — đảm bảo production build pass
3. ✅ Check broken links trong post mới
4. ✅ SEO score ≥80 (chạy `seo-optimizer` skill)
5. ✅ Image optimization done (chạy `image-optimizer` skill)
6. ✅ `git status` — confirm chỉ files mong muốn changed
7. ⚠️ Confirm với user trước khi `git commit` + `git push`
8. ✅ After push, monitor Vercel preview deploy
9. ✅ Test preview URL manually
10. ✅ Merge to main → production deploy

allowed-tools: Read, Grep, Glob   # read-only

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills