{
  "version": 1,
  "locale": "vi",
  "post": {
    "type": "post",
    "title": "Agent Skill có xịn đến mấy mà thiếu phần này cũng như mở quán Bún Bò Huế chỉ treo biển \"quán ăn sáng\"",
    "description": "Điểm tiếp cận quyết định 80% thành bại của người mới và cách tối ưu Description \"cái biển hiệu\" quan trọng nhất để AI không bỏ lỡ lệnh của bạn.",
    "url": "https://voquoccuong.com/blog/ai-agent/agent-skill-co-xin-den-may-ma-thieu-phan-nay-cung-nhu-mo-quan-bun-bo-hue-chi-tre/",
    "markdown_url": "https://voquoccuong.com/blog/ai-agent/agent-skill-co-xin-den-may-ma-thieu-phan-nay-cung-nhu-mo-quan-bun-bo-hue-chi-tre.md",
    "json_url": "https://voquoccuong.com/blog/ai-agent/agent-skill-co-xin-den-may-ma-thieu-phan-nay-cung-nhu-mo-quan-bun-bo-hue-chi-tre.json",
    "author": {
      "name": "Võ Quốc Cường",
      "role": "Founder & CEO EGANY · Co-founder AgentVid",
      "url": "https://voquoccuong.com/about/"
    },
    "category": {
      "slug": "ai-agent",
      "name": "AI Agent",
      "url": "https://voquoccuong.com/blog/ai-agent/"
    },
    "category_url": "https://voquoccuong.com/blog/ai-agent/",
    "published": "2026-05-03T07:22:15.019Z",
    "reading_minutes": 5,
    "image": "https://voquoccuong.com/blog-images/agent-skill-co-xin-den-may-ma-thieu-phan-nay-cung-nhu-mo-quan-bun-bo-hue-chi-tre/0.jpg",
    "source_url": "https://voquoccuong.substack.com/p/agent-skill-co-xin-en-may-ma-thieu",
    "content_markdown": "Năm ngoái mình bị “quê độ” trong lúc demo tạo skill bằng tay mà mãi SKILL không nhận, lý do đơn giản là mình đặt tên folder chứa skills bị sai (agent thay vì agent, claud thay vì claude).\n\nDù làm nghề giải pháp phần mềm hơn 16+ năm nhưng mình cũng mắc lỗi tương tự anh chị em mới khác, nên mọi người có bị thì cũng nên “quê độ” như mình nha (ủa) ^^\n\nSau đợt đó cũng “rảnh” nên ngồi tìm hiểu tài liệu từ Anthropic và đọc thêm blog của họ để đào sâu thêm cách viết skill sao cho hiệu quả, sẵn chia sẻ lại cho anh chị em trong cộng đồng luôn.\n\n![](https://voquoccuong.com/blog-images/agent-skill-co-xin-den-may-ma-thieu-phan-nay-cung-nhu-mo-quan-bun-bo-hue-chi-tre/0.jpg)\n\n## Agent Skill là gì? Tại sao nên dùng nó?\n\nHiểu đơn giản nó như là quy trình (SOP) và kỹ năng của nhân viên ảo, không khác gì quy trình với nhân viên thật.\n\n> Mình viết SOP 1 lần > nhân viên đọc > làm đúng vậy lần kế tiếp > không hỏi lại nữa.\n\n**Agent Skill cũng y chang vậy đó, mình đóng gói lại các bước và cách thức để AI Agent đọc và thực thi theo giống như mình đã mô tả.**\n\nChỗ này nhiều người dễ nhầm, nghe skill là nghĩ ngay tới chuyện kỹ thuật của mấy ông developer, nhưng thật ra không cần biết code vẫn có thể làm được. Vì vốn dĩ nó là câu chuyện của quy trình và hướng dẫn cho AI làm thay mình.\n\nKhông có skill thì mỗi lần Claude/Antigravity mở lên là bắt đầu từ số 0, mình phải prompt lại từ đầu, giải thích lại từ đầu hoặc.. nó tự đoán rồi làm trúng hay không là hên xui.\n\n## Cấu trúc SKILL chuẩn\n\nMỗi skill là 1 folder, bên trong chứa:\n\n- SKILL. md (bắt buộc): file chính, gồm YAML frontmatter + instructions\n- references/: tài liệu chi tiết, Claude chỉ đọc khi cần\n- scripts/: code chạy trực tiếp (Python stdlib only)\n- assets/: templates, fonts, images\n\nFolder name viết kiểu kebab-case, ví dụ: video-to-audio, sketch-note-graphic...\n\n![](https://voquoccuong.com/blog-images/agent-skill-co-xin-den-may-ma-thieu-phan-nay-cung-nhu-mo-quan-bun-bo-hue-chi-tre/1.png)\n\nSKILL. md mô tả rằng phải viết đúng case, viết sai là Claude không nhận.\n\n> Cái này thì mình viết sai thành skill.md hoặc Skill.md thì upload lên Claude nó vẫn tự chuyển lại thành SKILL.md cho mình luôn, chắc tài liệu đã cũ.\n\nNhưng mà thật ra phần quyết định skill có hoạt động hoặc nhận diện được đúng không thì.. *không phải đến từ chất lượng nội dung* (instruction) bên trong.\n\nMà là**DESCRIPTION.**\n\n## Progressive disclosure 3 tầng để AI nhận diện chính xác và.. kích hoạt SKILL\n\nPhần đầu file SKILL. md bắt buộc có 2 trường:\n\n- `name: tên skill, kebab-case`\n- `description: mô tả dưới 1024 ký tự, viết cho Claude đọc (không phải cho người)`\n\n![](https://voquoccuong.com/blog-images/agent-skill-co-xin-den-may-ma-thieu-phan-nay-cung-nhu-mo-quan-bun-bo-hue-chi-tre/2.png)\n\nChỗ này 90% anh em viết skill bỏ qua. Dành 3 tiếng viết instructions viết tới viết lui thật hay, còn description viết cho có.\n\n> Kết quả: Claude không bao giờ tự bật skill, phải gọi tay mỗi lần.\n\nCái này giống như mở quán ăn ồ ngon cỡ nào mà biển hiệu chỉ ghi “quán ăn sáng” thì không ai biết mình bán gì để mà ghé. Ghi đúng “bún bò Huế chính gốc, mở từ 6 sáng” thì khách đúng nhu cầu sẽ tự tìm tới.\n\nDescription cũng vậy. Nó là biển hiệu. Là điểm tiếp cận đầu tiên. AI chưa kịp đọc sâu bên trong thì đã phải quyết định: **có nên gọi skill này ra hay không rồi**.\n\nDescription không viết cho người đọc. Description viết cho AI đọc.. để nó quyết định CÓ BẬT SKILL HAY KHÔNG.\n\nMọi người có thể xem trong tài liệu của Anthropic có nhắc tới.\n\n1. Tầng 1 (YAML frontmatter): khoảng 100 tokens/skill, luôn được load. Claude scan qua tất cả skill để quyết định cái nào liên quan đến yêu cầu hiện tại.\n2. Tầng 2 (SKILL. md body): chỉ load khi Claude quyết định skill này cần được bật lên. Nên giữ dưới 500 dòng.\n3. Tầng 3 (references/): zero tokens cho đến khi Claude tự quyết định cần đọc thêm chi tiết.\n\n> Tại sao phải thiết kế vậy? Vì context window có giới hạn. Nếu bạn nạp 1001 skill mà cái nào cũng dài 1000 dòng, Claude sẽ không còn chỗ để suy nghĩ và làm việc. Thiết kế đúng 3 tầng thì nó nhẹ mà vẫn thông minh.\n\nCó một số con số cụ thể:\n\n- Description chung chung: tỉ lệ được gọi ~20%.\n- Có trigger phrases (câu user hay nói): ~50%.\n- Có trigger phrases + ví dụ tình huống cụ thể: 72-90%.\n\nKhác biệt không nằm ở skill phức tạp hay đơn giản. Nằm ở cách mọi người mô tả nó để AI nhận ra đúng lúc.\n\n## Checklist để viết Description đúng\n\n### 1. 5+ trigger phrases, cả tiếng Việt lẫn tiếng Anh.\n\nAnh chị em hay nói gì khi cần việc đó? Ghi lại đúng câu đó.\n\nVì user đâu có nói theo kiểu chung chung. Họ nói “coi giúp em file này”, “review bài viết này đúng policy fb chưa”, “so lại doanh thu tháng này”.\n\n> Description càng gần ngôn ngữ thật, Claude càng dễ bắt đúng.\n\n### 2. Mô tả TÌNH HUỐNG.. “khi user muốn...”\n\nKhông ghi “dùng để phân tích.” Ghi “khi user muốn so sánh doanh thu tháng này với tháng trước và tìm nguyên nhân chênh lệch.”\n\nMô tả tác vụ thì còn mơ hồ. Mô tả tình huống thì AI mới hiểu lúc nào nên nhảy vào.\n\n### 3. Bắt đầu bằng “BẤT CỨ KHI NÀO user...”\n\nCho Claude biết trigger condition.. giống như cài công tắc.\n\nNó nghe đơn giản thôi, nhưng đây là cách biến 1 đoạn mô tả thành điều kiện kích hoạt rõ ràng.\n\n### 4. Thêm ví dụ câu user có thể nói thật.\n\nLấy từ chat history thật. Không bịa.\n\nVí dụ thật luôn ăn đứt ví dụ tự nghĩ ra, vì nó phản ánh đúng cách user gọi việc trong đời thực.\n\n### 5. Dưới 1024 chars.. và KHÔNG dấu tiếng Việt.\n\nNghe kì cục nhưng description không dấu Claude xử lý mượt hơn. Mình cũng không hiểu tại sao nhưng.. số liệu nó vậy đó.\n\nĐừng tham nhét quá nhiều. Description không phải chỗ để kể hết mọi thứ skill biết làm. Nó chỉ cần đủ rõ để được gọi đúng.\n\n---\n\n**Nói vậy thôi.. instructions bên trong skill cũng quan trọng (không cãi được)**\n\nNhưng instructions hay mà description dở thì không ai (và không AI nào) tìm ra skill đó để dùng. Giống như sách hay mà bìa ghi “sách đọc”.. không ai mở.\n\nMình làm cả trăm mô tả giải pháp tối ưu conversion cho khách hàng. Bài học xuyên suốt: điểm tiếp cận đầu tiên vẫn quyết định 80% thành bại.\n\nVà Description chính là điểm tiếp cận của skill với AI.\n\nAnh chị em nào đã thử viết Agent Skill rồi.. description của anh chị viết gì? Quăng mình xem thử. Nhìn description là mình đoán được skill đó có tự bật nổi hay không. ^^\n\n#voquoccuong #EGANY\n\n---\n\n***Nguồn:***\n\n- *The Complete Guide to Building Skills for Claude (Anthropic, 2026)*\n- *Anthropic Engineering Blog: Equipping Agents for the Real World*\n- *Có lấy cảm hứng thêm từ bài của em* nữa hehe..",
    "headings": [
      {
        "level": 2,
        "text": "Agent Skill là gì? Tại sao nên dùng nó?",
        "slug": "agent-skill-la-gi-tai-sao-nen-dung-no"
      },
      {
        "level": 2,
        "text": "Cấu trúc SKILL chuẩn",
        "slug": "cau-truc-skill-chuan"
      },
      {
        "level": 2,
        "text": "Progressive disclosure 3 tầng để AI nhận diện chính xác và.. kích hoạt SKILL",
        "slug": "progressive-disclosure-3-tang-de-ai-nhan-dien-chinh-xac-va-kich-hoat-skill"
      },
      {
        "level": 2,
        "text": "Checklist để viết Description đúng",
        "slug": "checklist-de-viet-description-dung"
      },
      {
        "level": 3,
        "text": "1. 5+ trigger phrases, cả tiếng Việt lẫn tiếng Anh.",
        "slug": "1-5-trigger-phrases-ca-tieng-viet-lan-tieng-anh"
      },
      {
        "level": 3,
        "text": "2. Mô tả TÌNH HUỐNG.. “khi user muốn...”",
        "slug": "2-mo-ta-tinh-huong-khi-user-muon"
      },
      {
        "level": 3,
        "text": "3. Bắt đầu bằng “BẤT CỨ KHI NÀO user...”",
        "slug": "3-bat-dau-bang-bat-cu-khi-nao-user"
      },
      {
        "level": 3,
        "text": "4. Thêm ví dụ câu user có thể nói thật.",
        "slug": "4-them-vi-du-cau-user-co-the-noi-that"
      },
      {
        "level": 3,
        "text": "5. Dưới 1024 chars.. và KHÔNG dấu tiếng Việt.",
        "slug": "5-duoi-1024-chars-va-khong-dau-tieng-viet"
      },
      {
        "level": 2,
        "text": "Đọc tiếp",
        "slug": "doc-tiep"
      }
    ],
    "links": [
      {
        "text": "Đổi model ngon hơn có cứu được con AI Agent lúc đúng lúc sai không?",
        "url": "https://voquoccuong.com/blog/ai-agent/doi-model-ngon-hon-co-cuu-duoc-ai-agent-khong.md"
      },
      {
        "text": "HTML",
        "url": "https://voquoccuong.com/blog/ai-agent/doi-model-ngon-hon-co-cuu-duoc-ai-agent-khong/"
      },
      {
        "text": "JSON",
        "url": "https://voquoccuong.com/blog/ai-agent/doi-model-ngon-hon-co-cuu-duoc-ai-agent-khong.json"
      },
      {
        "text": "Cắm AI được vô ô chat Telegram/Zalo/Bitrix thì mới được gọi là AI Agent?",
        "url": "https://voquoccuong.com/blog/ai-agent/cam-ai-duoc-vo-o-chat-telegramzalobitrix-thi-moi-duoc-goi-la-ai-agent.md"
      },
      {
        "text": "HTML",
        "url": "https://voquoccuong.com/blog/ai-agent/cam-ai-duoc-vo-o-chat-telegramzalobitrix-thi-moi-duoc-goi-la-ai-agent/"
      },
      {
        "text": "JSON",
        "url": "https://voquoccuong.com/blog/ai-agent/cam-ai-duoc-vo-o-chat-telegramzalobitrix-thi-moi-duoc-goi-la-ai-agent.json"
      },
      {
        "text": "Tại sao Claude có Memory tự động rồi mà còn đưa thêm Context & Knowledge Files?",
        "url": "https://voquoccuong.com/blog/ai-agent/tai-sao-claude-co-memory-tu-dong-roi-ma-con-dua-them-context-knowledge-files.md"
      },
      {
        "text": "HTML",
        "url": "https://voquoccuong.com/blog/ai-agent/tai-sao-claude-co-memory-tu-dong-roi-ma-con-dua-them-context-knowledge-files/"
      },
      {
        "text": "JSON",
        "url": "https://voquoccuong.com/blog/ai-agent/tai-sao-claude-co-memory-tu-dong-roi-ma-con-dua-them-context-knowledge-files.json"
      }
    ],
    "related": [
      {
        "title": "Đổi model ngon hơn có cứu được con AI Agent lúc đúng lúc sai không?",
        "description": "Thuê đầu bếp sao Michelin về mà kho bẩn, chảo hỏng thì món vẫn dở. Vì sao đổi model không cứu được Agent, và khi nào doanh nghiệp không cần Agent.",
        "published": "2026-07-28T11:00:00.000Z",
        "category": "AI Agent",
        "url": "https://voquoccuong.com/blog/ai-agent/doi-model-ngon-hon-co-cuu-duoc-ai-agent-khong/",
        "markdown_url": "https://voquoccuong.com/blog/ai-agent/doi-model-ngon-hon-co-cuu-duoc-ai-agent-khong.md",
        "json_url": "https://voquoccuong.com/blog/ai-agent/doi-model-ngon-hon-co-cuu-duoc-ai-agent-khong.json"
      },
      {
        "title": "Cắm AI được vô ô chat Telegram/Zalo/Bitrix thì mới được gọi là AI Agent?",
        "description": "Sự thật cái nhầm lẫn này của anh chị em DN mà tôi gặp gần đây rất nhiều, thậm chí còn cho rằng cắm vô được Telegram/Zalo/Slack thì là đỉnh cao nhất, nhưng mà..",
        "published": "2026-06-30T13:26:31.446Z",
        "category": "AI Agent",
        "url": "https://voquoccuong.com/blog/ai-agent/cam-ai-duoc-vo-o-chat-telegramzalobitrix-thi-moi-duoc-goi-la-ai-agent/",
        "markdown_url": "https://voquoccuong.com/blog/ai-agent/cam-ai-duoc-vo-o-chat-telegramzalobitrix-thi-moi-duoc-goi-la-ai-agent.md",
        "json_url": "https://voquoccuong.com/blog/ai-agent/cam-ai-duoc-vo-o-chat-telegramzalobitrix-thi-moi-duoc-goi-la-ai-agent.json"
      },
      {
        "title": "Tại sao Claude có Memory tự động rồi mà còn đưa thêm Context & Knowledge Files?",
        "description": "Bài giải đáp câu hỏi tôi nhận được từ cộng đồng CxO AI Automation",
        "published": "2026-03-27T05:51:25.469Z",
        "category": "AI Agent",
        "url": "https://voquoccuong.com/blog/ai-agent/tai-sao-claude-co-memory-tu-dong-roi-ma-con-dua-them-context-knowledge-files/",
        "markdown_url": "https://voquoccuong.com/blog/ai-agent/tai-sao-claude-co-memory-tu-dong-roi-ma-con-dua-them-context-knowledge-files.md",
        "json_url": "https://voquoccuong.com/blog/ai-agent/tai-sao-claude-co-memory-tu-dong-roi-ma-con-dua-them-context-knowledge-files.json"
      }
    ]
  }
}