OpenSkillIndex← back to search
claude-code

Ai-toolkit cc-agent-audit

Claude Code 專案配置審計。觸發：review/優化 CLAUDE.md、skills、settings、定期清洗累積內容、新專案上線前檢查。

install
source · Clone the upstream repo
git clone https://github.com/cablate/ai-toolkit
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/cablate/ai-toolkit "$T" && mkdir -p ~/.claude/skills && cp -r "$T/domain-skills/claude-code/cc-agent-audit" ~/.claude/skills/cablate-ai-toolkit-cc-agent-audit && rm -rf "$T"
manifest: domain-skills/claude-code/cc-agent-audit/SKILL.md
source content

Claude Code 專案配置審計

系統化 review 一個 Claude Code 專案或 agent 的配置品質，確保 prompt 精簡、結構清晰、資訊零損失。

核心原則：搬移而非刪除

優化配置時，一律採用「搬移」而非「刪除」：

操作錯誤做法正確做法
畢業一條 Lesson從 CLAUDE.md 刪除搬到共用 rules 或 skill references/
精簡 description移除細節文字先把細節移入 SKILL.md 正文，再縮短 description
刪除一條使用者期待直接刪除搬到對應的 skill
合併重複原則刪較弱的那個保留主版本，標記次版本為 @import 或 reference

審計保證：優化後，所有資訊仍存在於系統的某處，品質不降級。

三層分離原則

解決「description 要豐富觸發 vs. token 要最小」的矛盾：

Layer 1: description（每輪注入 system-reminder）= 觸發條件 ONLY，≤2 句
Layer 2: SKILL.md 正文（按需載入）= 能力範圍、工作流程、品質標準
Layer 3: references/（深度載入）= 知識庫、案例、歷史教訓

每層的職責不互相跨越。詳見 

references/three-layer-principle.md
。

前置載入（按需）

Skill何時需要
cc-prompt-craft
審查 CLAUDE.md 文本品質、cache 結構
cc-agent-design
審查工具配置、模型選擇、dispatch prompt
cc-cost-engineering
審查 token 消耗、cache 效率、model 成本矩陣
cc-harness-patterns
審查 deferred loading、cache 穩定性
agentskill-expertise
審查 skill 設計哲學、Metadata-driven Triggering

5 項檢查

依序執行，每項產出 

PASS / ISSUE(N)
結論。

Check 1：CLAUDE.md 文本品質

讀取 

CLAUDE.md
，逐項檢查：

檢查項PASS 條件常見問題
角色定義寫人格不寫機制。一句話設定語氣基調描述 AI 的技術機制而非個性特質
使用者期待只放跟所有對話都相關的通用事項任務特定指令（如寫作格式）坐在 CLAUDE.md 裡
核心原則不與 
.claude/rules/
的任何檔案重複		原則內容 rules 已有，出現在 CLAUDE.md 造成雙重定義
結構順序穩定內容在前，Lessons Learned 在最後易變的 Lessons 插在中間破壞 cache 穩定性
Lessons≤10 條，無跟 rules 重複的已被共用規則涵蓋的條目沒有畢業
Skill 關鍵字表（若有）所有引用的 skill 名稱有對應的 SKILL.md 存在引用已刪除或改名的 skill

Check 2：Skill Description 品質

列出所有 

.claude/skills/*/SKILL.md
，逐個檢查 frontmatter：

檢查項PASS 條件常見問題
有 frontmatter
---
包圍的 YAML block 存在		缺少 frontmatter，Claude Code 無法顯示於 system-reminder
description 長度≤2 句話觸發情境、更新時機、能力列表全塞進 description
觸發條件包含「觸發：」或「Use when:」只寫功能描述，沒說什麼時候用
無冗餘內容能力範圍、更新政策不在 description 裡這些屬於 SKILL.md 正文，不該佔 system-reminder token
格式統一統一用一種觸發格式有的中文「觸發時機」有的英文「Use when」混用

估算 token 節省：skill 數量 × 每個 skill 平均精簡 token 數 = 每輪節省量。

Check 3：Settings 配置

讀取 

settings.local.json
或 
settings.json
，檢查：

檢查項PASS 條件常見問題
工具最小化allow list 只有這個 agent 真的需要的工具一次性加了全套工具，實際用不到
無冗餘權限wildcard（
*
）存在時無個別條目
mcp__tool__*
同時列了 7 條個別權限
deny rules執行 bash 的 agent 有 deny rules無 deny 導致 agent 可執行危險指令
model 適配model 匹配任務複雜度（見 cc-cost-engineering 矩陣）簡單反思任務用 opus，浪費費用
MCP server 數量
.mcp.json
的 server 數量合理，無不使用的 server		MCP server 的工具 schema 每輪注入 prompt，多餘 server 增加 token + cache break 風險

Check 4：Rules 對齊

確認 

.claude/rules/
的內容與 
CLAUDE.md
無矛盾：

檢查項PASS 條件
無相互矛盾rules 與 CLAUDE.md 的指令方向一致
無跨檔重複同一條指令不同時出現在 rules 和 CLAUDE.md
@import 有效若使用 @import，被引用的檔案存在

Check 5：跨檔一致性

若有 persona/soul.md，檢查與 CLAUDE.md 的一致性：

檢查項PASS 條件常見問題
角色定義對齊CLAUDE.md 角色定義 ⊆ soul.md Who I AmCLAUDE.md 寫「AI 助手」但 soul.md 寫有個性的角色名
原則不矛盾CLAUDE.md 核心原則不與 soul.md Work Principles 衝突同一條原則兩邊措辭或方向不同
使用者期待不重複CLAUDE.md 使用者期待不與 soul.md Quirks/How I Sound 重複「emoji 節制」同時出現在兩處

若無 persona/soul.md，此 check 標記 N/A。

執行模式

模式觸發方式行為
review"review X 的配置" / "audit this project"唯讀，產出報告，不改任何檔案
fix"整理 X 的配置" / "optimize this project"產出報告 + 列出所有預計改動，等確認後才執行
batch"review 所有 agent"逐個 agent/專案產出獨立報告

輸出格式

# 配置審計報告：{project/agent name}

## Summary
- CLAUDE.md: PASS / ISSUE(N)
- Skills: PASS / ISSUE(N)
- Settings: PASS / ISSUE(N)
- Rules: PASS / ISSUE(N)
- Consistency: PASS / ISSUE(N) / N/A

## Issues

### [ISSUE-1] {檢查項}
- Current: ...
- Problem: ...
- Suggested fix: ... （含具體 before/after）
- Migration: 被移除的內容搬到哪裡

### [ISSUE-2] ...

## Token Impact
- Skill descriptions: ~{N} tokens/turn saved
- CLAUDE.md: ~{N} tokens saved
- Rules consolidation: {N} fewer system-reminder injections

安全規範

  • review 模式是嚴格唯讀，不寫入任何檔案
  • fix 模式必須先列出所有計畫變更（diff 格式），等待使用者確認後才執行
  • Lessons 永不自動刪除——只標記為「畢業候選」，由使用者決定
  • Description 精簡必須先確認細節已移入 SKILL.md 正文，才縮短 description

依賴的知識來源

  • cc-prompt-craft
    ：prompt 結構、cache 優化、17 種設計模式
  • cc-agent-design
    ：工具最小化、模型選擇、dispatch prompt
  • cc-cost-engineering
    ：token 成本、cache 中斷原因、model 成本矩陣
  • cc-harness-patterns
    ：deferred loading、cache 穩定性
  • agentskill-expertise
    ：skill 設計哲學（Metadata-driven、Description-Driven Triggering）