Agent Prompting & Context Engineering Guide

現代 AI Agent 提示詞格式規範、Agent Skill 開發編排、與上下文工程（Context Engineering）之全方位權威指南、實戰範例庫與可調用技能庫。

---

專案核心使命

隨著大語言模型（LLM）由「對話型問答」進化為「具備自主行動與工具調用能力的 Agent」，傳統的 Prompt Engineering 已無法滿足複雜系統的穩定性需求。

本專案全面轉型為**「教學指南 (Docs) + 可調用實戰技能 (Skills) + 實戰範例庫 (Examples)」**的三合一架構，深入拆解三大核心領域：

1. 如何制定 Agent 提示的 Prompting 格式與技巧：從 System Prompt 5 層分層架構、XML 標籤結構化語法、ReAct 與 Plan-and-Solve 推理協議，到抗提示注入、消除幻覺與主動澄清防護。
2. Agent Skill 的開發、撰寫、編排技巧：從標準 SKILL.md 規範、YAML Frontmatter 觸發工程、漸進式揭露（Progressive Disclosure）到多技能動態路由（Router）、管線鏈結（Chaining）與交接（Handoff）。
3. 上下文工程的方法與架構：從靜態/半靜態/動態 3 層上下文架構、Token 預算分配、Prompt Caching 快取防穿透優化、工作記憶（Scratchpad）與製品卸載（Artifacts），到克服 Lost-in-the-Middle 與上下文腐爛（Context Rot）的壓縮技術。

---

全站核心導覽地圖 (Documentation Hub)

Agent-Prompting-Guide/
├── 📚 1. 深度教學指南庫 (docs/)
│   ├── 01-agent-prompting/         # 提示詞格式與技巧
│   │   ├── 01-system-prompt-architecture.md   # System Prompt 5 層結構化架構
│   │   ├── 02-prompt-formats-and-schemas.md   # XML 標籤語法與 JSON Schema 約束
│   │   ├── 03-agent-reasoning-techniques.md   # ReAct, Plan-and-Solve, Reflection
│   │   └── 04-defensive-prompting-safety.md   # 防注入、抗幻覺與主動澄清門禁
│   ├── 02-skill-engineering/       # Skill 開發與編排
│   │   ├── 01-skill-specification-standard.md # SKILL.md 標準規格與 Frontmatter
│   │   ├── 02-progressive-disclosure.md       # 漸進式揭露哲學與 references 拆分
│   │   ├── 03-skill-orchestration-patterns.md # Router, Chaining, Handoff 編排
│   │   └── 04-testing-and-evaluating-skills.md # Skill 觸發測試、紅隊測試與評測
│   └── 03-context-engineering/     # 上下文工程架構
│       ├── 01-context-architecture-layers.md  # 3 層架構與 Token 預算規劃
│       ├── 02-context-caching-strategies.md   # Prompt Caching 前綴優化實踐
│       ├── 03-memory-management-patterns.md   # Working Memory, Scratchpad, Artifacts
│       └── 04-preventing-context-rot.md       # Lost-in-the-middle, 壓縮與修剪
│
├── 🛠️ 2. 實用可調用技能庫 (Skills for Agents)
│   ├── agent-prompt-craft/         # 指導/自動產出高品質 Agent Prompt 的專任技能
│   ├── skill-creator-expert/       # 指導/重構合規 Agent Skill 的專任技能
│   ├── skill-orchestrator/         # 設計多技能編排、路由與交接封包的專任技能
│   └── context-architect/          # 規劃上下文分層、預算計算與快取佈局的專任技能
│
└── 💡 3. 實戰範例與模板庫 (examples/)
    ├── prompts/                    # 可直接複製投入生產的 Agent Prompt 模板
    │   ├── react-agent-prompt.md              # 自主 ReAct 修復程式碼代理
    │   ├── structured-json-agent-prompt.md    # 嚴格 JSON Schema 資料萃取代理
    │   └── clarification-guardrail-prompt.md  # 防禦性與主動澄清雲端維運代理
    ├── skills/                     # 標準 Skill 實作範例
    │   ├── clean-code-principle/              # 整潔程式碼與壞味道重構指導範例技能 (含雙模組 references)
    │   ├── google-typescript-style/           # Google TypeScript 官方規範轉換範例技能 (語意提煉 + 漸進式揭露)
    │   ├── data-analyst-skill/                # 唯讀資料庫分析與慢查優化技能
    │   └── api-integrator-skill/              # 具備指數退避與熔斷的 API 整合技能
    └── context/                    # 上下文設定檔與工作記憶範本
        ├── token-budget-strategy.md           # 64K 視窗預算設定檔 (JSON)
        └── scratchpad-memory-template.md      # XML 工作草稿覆寫狀態機

---

可調用 Skills 安裝與使用 (npx skills)

本專案遵循標準 SKILL.md 與 catalog.yaml 規格，相容於 skills CLI、Google Antigravity、Claude Code、Cursor 與 OpenAI Codex。

查詢可用技能清單：

npx skills add slime21023/Agent-Prompting-Guide --list

一鍵安裝全部專用技能：

npx skills add slime21023/Agent-Prompting-Guide --skill '*'

依需求安裝個別技能：

• 安裝 Agent 提示詞設計專責技能：

  npx skills add slime21023/Agent-Prompting-Guide --skill agent-prompt-craft

• 安裝 Agent Skill 規範化開發專責技能：

  npx skills add slime21023/Agent-Prompting-Guide --skill skill-creator-expert

• 安裝多技能編排與調度專責技能：

  npx skills add slime21023/Agent-Prompting-Guide --skill skill-orchestrator

• 安裝上下文工程與快取架構專責技能：

  npx skills add slime21023/Agent-Prompting-Guide --skill context-architect

---

三大核心主題精要

主題一：Agent 提示詞的結構化 5 層架構

+-----------------------------------------------------------+
| 1. 身份與核心任務 (Identity & Core Mission)                |
+-----------------------------------------------------------+
| 2. 能力邊界與授權範圍 (Capabilities & Operational Bounds)   |
+-----------------------------------------------------------+
| 3. 推理與執行協議 (Reasoning & Execution Protocols)        |
+-----------------------------------------------------------+
| 4. 工具使用與安全防護 (Tool Usage & Guardrails)            |
+-----------------------------------------------------------+
| 5. 輸出協議與狀態格式 (Output Format & State Machine)       |
+-----------------------------------------------------------+

• 核心理念：拋棄小說式擬人人設，以確定性操作系統指令規範 Agent。
• 詳見章節：01-system-prompt-architecture.md

---

主題二：Agent Skill 的漸進式揭露 (Progressive Disclosure)

[第一級: catalog.yaml / Frontmatter (~50 Tokens)]
   | (意圖命中激活)
   v
[第二級: SKILL.md 核心工作流與決策樹 (~800 Tokens)]
   | (依條件按需局部載入)
   v
[第三級: references/*.md 深度模板與語法清單 (按需 1K~3K Tokens)]

• 核心理念：入口保持輕量，僅在 Agent 遇到特定分支條件時才動態載入深層參考資料，避免注意力稀釋與 Token 浪費。
• 詳見章節：02-progressive-disclosure.md

---

主題三：上下文工程與快取前綴不變性 (Context Caching & Invariance)

[最穩定 前綴] System Prompt (永久不變) -> 100% Cache Hit
      v
[次穩定 配置] AGENTS.md + 字典排序工具宣告 -> 100% Cache Hit
      v
[任務級 技能] 啟用中 SKILL.md 指令 -> 任務內 Cache Hit
      v
[高動態 尾端] 對話歷史 + 最新使用者輸入 + 工具觀察

• 核心理念：杜絕在提示詞開頭注入動態時間戳或隨機種子，確保前綴位元組 100% 一致，享有 80%+ 的成本折抵與顯著推論加速。
• 詳見章節：02-context-caching-strategies.md

---

貢獻與開發指南

若您欲為本專案新增教學指南、實戰範例或全新 Agent Skill，請詳閱 AGENTS.md。 所有變更必須通過 AGENTS.md 驗證檢核清單，並同步更新 catalog.yaml 與 README.md。

---

授權條款

本專案採用 MIT License 授權開放開源社群自由學習與商業應用。