Claude Code Skills 2.0 Architecture Guide¶

繁體中文總結¶

Yuker 提出 Claude Code Skills 的架構演進論：單一 SKILL.md 檔案已無法應對複雜場景，必須轉向模組化的「Skill 2.0 架構」，透過知識原子化、漸進式披露（Progressive Disclosure）原則，將龐大的指令體系拆解成獨立、內聚、可管理的知識積木，從根本上解決上下文負擔與維護困境。

核心洞察：從煉金術到現代化學¶

問題診斷： 單檔案思維的兩大致命傷
1. 上下文的無形枷鎖 - 將所有指令、規則、示例、文件塞入單一 SKILL.md，每次觸發 Skill 都是一次沉重的記憶負擔。Claude 必須「扛著整本百科全書」工作，導致： - 效能下降（加載時間增加） - 指令漂移（上下文接近極限時遺忘關鍵指令） - 成本超支（更大上下文 = 更高計費）

維護的噩夢迷宮 - 超過 500 行的 SKILL.md 成為維護噩夢：邏輯混亂、可讀性差、修改風險高（高度耦合導致「改 A 壞 B」）。

解決方案： Skill 2.0 的模組化思維
核心原則是「漸進式披露」：SKILL.md 成為輕量級的「目錄索引」，Claude 先載入目錄，再按需「翻閱」具體章節（引用的 .md、.py、.json 檔案）。這就像讀書：先看目錄了解結構，再按興趣深入特定章節。

關鍵架構規則： - 唯一強制要求： SKILL.md 必須存在，否則 Claude 不會識別為 Skill - 其他完全自由： 檔案名稱、資料夾結構、檔案類型都可自由命名（甚至中文） - 不會自動載入： Claude 不會自動讀取其他檔案，必須在 SKILL.md 中明確引用

兩種經典架構模式¶

1. 知識庫型（Knowledge Base）¶

適用場景： 提供靜態、結構化的知識
典型案例： API 文件、框架最佳實踐、團隊設計規範

目錄結構範例：

📁 company-knowledge/
├── 📄 SKILL.md          ← 知識索引
└── 📁 knowledge/
    ├── 📄 術語表.md
    ├── 📄 產品FAQ.md
    └── 📄 報銷流程.md

工作原理： 當用戶問「公司的 OKR 是什麼意思」時，Claude 會： 1. 先看 SKILL.md，發現這是術語問題 2. 打開 knowledge/術語表.md，找到 OKR 解釋 3. 回答用戶

不會打開 產品FAQ 或報銷流程，因為與當前問題無關 —— 這就是「按需取用」的威力。

2. 工作流型（Workflow）¶

適用場景： 完成多步驟任務
典型案例： 寫周報、會議紀要、文章發布

目錄結構範例：

📁 weekly-report/
├── 📄 SKILL.md              ← 總指揮
├── 📁 workflow/
│   ├── 📄 step1-收集信息.md
│   ├── 📄 step2-整理內容.md
│   └── 📄 step3-生成周報.md
├── 📁 templates/
│   └── 📄 周報模板.md
└── 📁 rules/
    └── 📄 寫作規範.md

工作原理： 當用戶說「幫我寫周報」時，Claude 會： 1. 看 SKILL.md，了解整體流程 2. 依次執行 step1 → step2 → step3 3. 在 step3 時打開「周報模板」格式化輸出 4. 每完成一步在清單上打勾 ✓

實戰案例：10 分鐘打造 AI 周報助手¶

Yuker 提供完整的實作步驟（含所有模板檔案內容）：

第一步： 創建資料夾結構

mkdir -p weekly-report-ai/{workflow,templates,rules}

第二步： 編寫「寫作規範」（rules/writing-guide.md） - 語言風格：簡潔專業、數據導向、避免口語化 - 內容要求：量化結果、解決方案、工作計畫 - 格式要求：Markdown、加粗重點、列表不超過 5 條

第三步： 編寫「周報模板」（templates/report-template.md）包含：本周概要、完成事項、進行中、問題與風險、下周計畫

第四步： 編寫工作流步驟（workflow/step1-3） - step1-collect.md：收集本周工作信息（追問細節技巧） - step2-organize.md：整理分類（分組、提煉、量化、排序） - step3-generate.md：生成最終周報（填入模板、檢查格式）

第五步： 編寫主控檔案（SKILL.md） - YAML frontmatter：name、description（觸發條件） - 工作流程表格：列出 3 步驟 + 引用連結 - 參考資料：寫作規範、周報模板

第六步： 見證奇跡輸入 /weekly-report-ai 或「幫我寫個周報」，Claude 會按照 workflow 設定工作：問 → 整理 → 生成。

三個進階技巧¶

1. 配置檔案實現「一鍵切換」
針對不同場景（如不同部門）使用同一 Skill：

// config/tech-team.json
{
  "team_name": "技術部",
  "focus_areas": ["代碼提交", "Bug修復", "技術方案"],
  "report_style": "數據導向，多用指標"
}

在 SKILL.md 引用：請先讀取 config/tech-team.json

2. 禁止清單防止犯錯
創建 rules/dont-do.md，明確列出禁止行為： - 禁止編造用戶沒提到的工作 - 禁止使用表情符號 - 禁止超長段落（>3 句話） - 禁止模糊表達（「一些」、「大概」）

3. 檢查清單確保品質
在 workflow 最後加入 step4-review.md，讓 Claude 自檢： - 格式是否符合模板？ - 有無錯別字或語法錯誤？ - 數據是否準確（沒有編造）？ - 是否違反禁止清單？ - 內容是否簡潔？

方法論啟示¶

Yuker 強調這不僅是技術優化，更是思維轉變：

從「提示詞工程」到「架構設計」
- 過去：調配「魔法藥水」（靠運氣的 Prompt） - 現在：構建「分子結構」（穩定可預測的架構）

從「使用者」到「設計者」
你不是在「用」AI，而是在「構建數字員工的大腦」。每個結構精良的 Skill 都是為智能時代添上的堅實基石。

English Summary¶

Yuker argues that Claude Code Skills must evolve from single-file SKILL.md thinking to a modular "Skill 2.0 architecture." By atomizing knowledge and applying progressive disclosure principles, developers can transform monolithic instruction sets into independent, cohesive, manageable knowledge blocks, fundamentally solving context burden and maintenance nightmares.

Core Insight: From Alchemy to Modern Chemistry¶

Problem Diagnosis: Two Fatal Flaws of Single-File Thinking

The Invisible Shackles of Context - Cramming all instructions, rules, examples, and references into a single SKILL.md creates a heavy memory burden with every skill invocation. Claude must "carry an entire encyclopedia" while working, leading to:
Performance degradation (increased loading time)
Instruction drift (forgetting key instructions when context nears limits)
Budget overruns (larger context = higher billing)
The Maintenance Nightmare Maze - A SKILL.md exceeding 500 lines becomes a maintenance nightmare: logical chaos, poor readability, high modification risk (tight coupling causes "fix A, break B" scenarios).

Solution: Skill 2.0's Modular Thinking

The core principle is "progressive disclosure": SKILL.md becomes a lightweight "table of contents," Claude first loads the index, then "turns to specific chapters" (referenced .md, .py, .json files) as needed. Like reading a book: first scan the table of contents to understand structure, then dive into specific chapters based on interest.

Key Architecture Rules: - Only mandatory requirement: SKILL.md must exist, or Claude won't recognize it as a skill - Everything else is free: File names, folder structure, file types can be named freely (even in Chinese) - No auto-loading: Claude doesn't automatically read other files; must explicitly reference them in SKILL.md

Two Classic Architecture Patterns¶

1. Knowledge Base Type¶

Use Cases: Providing static, structured knowledge
Typical Examples: API documentation, framework best practices, team design specifications

Directory Structure Example:

📁 company-knowledge/
├── 📄 SKILL.md          ← Knowledge index
└── 📁 knowledge/
    ├── 📄 术语表.md
    ├── 📄 产品FAQ.md
    └── 📄 报销流程.md

How It Works: When user asks "What does OKR mean in our company?", Claude will: 1. Check SKILL.md first, identifies this as a terminology question 2. Open knowledge/术语表.md, find OKR explanation 3. Answer the user

Won't open product FAQ or reimbursement process because they're irrelevant to current question — this is the power of "load on demand."

2. Workflow Type¶

Use Cases: Completing multi-step tasks
Typical Examples: Writing weekly reports, meeting minutes, article publishing

Directory Structure Example:

📁 weekly-report/
├── 📄 SKILL.md              ← Master controller
├── 📁 workflow/
│   ├── 📄 step1-collect.md
│   ├── 📄 step2-organize.md
│   └── 📄 step3-generate.md
├── 📁 templates/
│   └── 📄 report-template.md
└── 📁 rules/
    └── 📄 writing-guide.md

How It Works: When user says "help me write weekly report", Claude will: 1. Check SKILL.md, understand overall workflow 2. Execute step1 → step2 → step3 sequentially 3. Open "report template" during step3 to format output 4. Check off each completed step ✓

Practical Case: Build AI Weekly Report Assistant in 10 Minutes¶

Yuker provides complete implementation steps (with all template file contents):

Step 1: Create folder structure

mkdir -p weekly-report-ai/{workflow,templates,rules}

Step 2: Write "Writing Guidelines" (rules/writing-guide.md) - Language style: concise, professional, data-driven, avoid colloquialism - Content requirements: quantified results, solutions, work plans - Format requirements: Markdown, bold emphasis, lists ≤5 items

Step 3: Write "Report Template" (templates/report-template.md) Includes: Weekly overview, completed items, in-progress, issues & risks, next week's plan

Step 4: Write workflow steps (workflow/step1-3) - step1-collect.md: Collect weekly work info (techniques for asking follow-up questions) - step2-organize.md: Organize & categorize (group, refine, quantify, sort) - step3-generate.md: Generate final report (fill template, check format)

Step 5: Write master control file (SKILL.md) - YAML frontmatter: name, description (trigger conditions) - Workflow table: list 3 steps + reference links - Reference materials: writing guidelines, report template

Step 6: Witness the magic Input /weekly-report-ai or "help me write weekly report", Claude follows workflow: ask → organize → generate.

Three Advanced Techniques¶

1. Config Files for "One-Click Switching"
For different scenarios (e.g., different departments) using same skill:

// config/tech-team.json
{
  "team_name": "Tech Team",
  "focus_areas": ["Code commits", "Bug fixes", "Technical proposals"],
  "report_style": "Data-driven, use metrics"
}

Reference in SKILL.md: Please first read config/tech-team.json

2. "Don't Do" List to Prevent Mistakes
Create rules/dont-do.md, explicitly list prohibited behaviors: - Don't fabricate work content user didn't mention - Don't use emojis - Don't write long paragraphs (>3 sentences) - Don't use vague expressions ("some", "probably")

3. Checklist to Ensure Quality
Add step4-review.md at end of workflow, let Claude self-check: - Does format match template? - Any typos or grammar errors? - Is data accurate (no fabrication)? - Any violations of don't-do list? - Is content concise?

Methodological Insights¶

Yuker emphasizes this is not just technical optimization, but a mindset shift:

From "Prompt Engineering" to "Architecture Design"
- Before: Concocting "magic potions" (luck-based prompts) - Now: Building "molecular structures" (stable, predictable architectures)

From "User" to "Designer"
You're not "using" AI, but "building the brain of a digital employee." Every well-structured skill is a solid cornerstone added to the intelligent era.

Key Takeaways¶

Modular architecture is essential for complex Claude Code skills beyond basic use cases
Progressive disclosure reduces context burden and improves performance
Two primary patterns (Knowledge Base + Workflow) cover most skill scenarios
Explicit references required - Claude won't auto-load files without SKILL.md references
Advanced techniques (config files, don't-do lists, checklists) enhance reliability
Mindset shift from prompt engineering to systematic architecture design

Original article: https://x.com/YukerX/status/2014537059504161173
Author's previous article: "Skills Guide for Beginners"
Example implementation: Weekly Report AI Assistant (see article for full templates)