🤖claude code底层代码引出的agent，skill，prompt编写指南
type
Post
status
Published
date
Apr 3, 2026
slug
claude-code-agent-skill-prompt-guide
summary
从Claude Code源码出发，详解Agent、Skill、Prompt、Hook的完整编写指南，涵盖目录结构、配置体系、参数替换、记忆系统、金融研究和数据分析实战案例。
tags
开发
工具
category
技术分享
icon
password
Comment
快速入门 — 目录结构与配置体系
从源码出发，理解 Claude Code 完整的文件加载机制，建立正确的心智模型。
1.1 两层目录结构
Claude Code 在两个层级读取配置：用户级（
~/.claude/）和项目级（.claude/）。项目级优先级更高，本地覆盖文件（*.local.*）优先级最高。⚠️ 关键陷阱：Skill 文件必须放在子目录中：.claude/skills/<n>/SKILL.md。直接放.claude/skills/name.md将无法被识别。这是loadSkillsDir.ts的加载逻辑决定的。
1.2 Settings 优先级
配置按以下顺序合并，后者覆盖前者。Managed（策略）设置优先级最高，无法被用户或项目覆盖。
优先级 | 来源 | 路径示例 | 说明 |
1（最低） | Built-in defaults | — | 代码内置默认值 |
2 | User settings | ~/.claude/settings.json | 用户全局配置 |
3 | Project settings | .claude/settings.json | 项目配置，可提交 |
4 | Local settings | .claude/settings.local.json | 本地覆盖，不提交 |
5（最高） | Managed / Policy | /etc/claude-code/managed-settings.json | 企业策略，强制生效 |
1.3 CLAUDE.md 加载机制
CLAUDE.md 文件按固定顺序加载，越晚加载优先级越高（模型更关注后出现的指令）。
重要参数（源码核实）
参数 | 值 | 含义 |
MAX_MEMORY_CHARACTER_COUNT | 40000 | 单个 CLAUDE.md 文件建议字符上限 |
MAX_INCLUDE_DEPTH | 5 | @include 嵌套最大深度 |
HTML 注释 | 自动剥离 | 块级 <!-- ... --> 会被 stripHtmlComments() 移除 |
@include 语法
在 CLAUDE.md 中可用
@ 前缀引入其他文件，支持多种路径形式：glob 作用域规则（paths: frontmatter）
.claude/rules/ 目录中的 .md 文件可以用 paths: frontmatter 控制该规则仅在操作匹配路径时注入，节省 token。1.4 settings.json 与 Hooks 配置
~/.claude/settings.json 控制全局行为，其中最重要的是 hooks。Hooks 是在 Claude 执行工具调用前后自动运行的 shell 命令。⚠️ 关键警告：Hook 命令通过 stdin 接收 JSON 输入，必须用jq解析，不能使用{{file_path}}这类模板变量语法。
Hook 类型完整参考
时机 | 事件 | 典型用途 |
PreToolUse | 工具调用前 | 验证、拦截危险操作 |
PostToolUse | 工具调用后 | 自动格式化、lint、测试 |
Notification | 通知时 | 桌面推送、Slack 消息 |
Stop | 会话结束 | 最终检查、日志归档 |
SubagentStop | 子 Agent 结束 | 汇总 sub-agent 结果 |
Hook 命令可选字段
字段 | 类型 | 说明 |
timeout | number (秒) | 超时时间，防止卡住 |
statusMessage | string | 执行时显示在 spinner 的消息 |
async | boolean | 后台执行，不阻塞 Claude |
asyncRewake | boolean | 后台执行，exit code 2 时唤醒模型 |
once | boolean | 只执行一次，然后移除 |
if | string | 权限规则语法的条件过滤 |
自定义 Agent 完全指南
基于
loadAgentsDir.ts 源码，掌握 Agent frontmatter 的每个字段及其精确行为。2.1 Agent Frontmatter 完整参考
Agent 文件放置于
.claude/agents/<n>.md 或 ~/.claude/agents/<n>.md。字段 | 类型 | 默认值 | 源码核实行为 |
name | string | 必填 | Agent 的唯一标识符 |
description | string | 必填 | 模型据此决定何时自动调用该 Agent |
tools | string[] | undefined（=所有工具） | 缺省=ALL； []=无工具 |
disallowed-tools | string[] | [] | 明确禁止的工具列表 |
model | string | 继承父级 | 'inherit' 使用父级模型 |
effort | string/int | normal | 支持 low/medium/high 或整数 |
memory | string | — | user/project/local 三种作用域 |
omitClaudeMd | boolean | false | true=不加载 CLAUDE.md 层级 |
max-turns | number | — | 最大对话轮数 |
isolation | string | — | 在独立 git worktree 中运行 |
background | boolean | false | 始终作为后台任务运行 |
hooks | HooksSettings | {} | Agent 专属 hooks |
skills | string[] | [] | 预加载的 skill 名称列表 |
2.2 关键设计模式（来自内置 Agent）
Pattern A：只读快速探索 Agent
💡 为什么用 disallowed-tools 而非 tools：若用白名单，未来新增只读工具需手动添加。用黑名单只需列出写操作工具。
Pattern B：通用全能 Agent
Pattern C：带跨会话记忆的专业 Agent
Pattern D：带内联 Hook 的 TDD Agent
2.3 Agent Prompt 编写原则
来自
prompt.ts 的指导：- Brief the agent like a smart colleague who just walked into the room
- Explain what you're trying to accomplish and why
- Terse command-style prompts produce shallow, generic work
- Never delegate understanding — Don't write "based on your findings, fix the bug"
⚠️ Fork Agent 注意：不应在 fork agent 上设置 model（不同模型无法复用父级的 prompt cache）。
Skill 编写实战
基于
loadSkillsDir.ts 和 skillify.ts，掌握可复用工作流的完整编写方法。3.1 文件位置规范
Skill 文件必须放在子目录中：
3.2 关键区别：Agent 与 Skill 的工具默认行为
⚠️ 最重要的陷阱：
- Agent 的tools缺省 → 所有工具可用
- Skill 的allowed-tools缺省 → 没有任何工具！
Skill 必须显式声明allowed-tools。
3.3 参数替换语法
Skill 支持参数化，通过 frontmatter 的
arguments 字段声明参数名，在 body 中用 $name 语法引用。3.4 allowed-tools 权限规则语法
模式 | 类型 | 匹配示例 |
Bash | tool-wide | 任何 bash 命令 |
Bash(git commit) | exact match | 只有 git commit |
Bash(git:*) | prefix match | git add、git push 等 |
Bash(npm run *) | wildcard | npm run test、npm run build |
Read(*.py) | wildcard | 只读取 Python 文件 |
Write(src/**) | wildcard | 只写 src/ 目录下的文件 |
💡 最小权限原则：不要懒惰地写Bash，应精确声明需要的命令范围。
3.5 when_to_use 编写规则
when_to_use 是告诉模型何时自动调用该 Skill 的关键字段。Start with "Use when..." and include trigger phrases。3.6 完整 Skill 模板
📝 Skill 步骤标注规范：
-**Success criteria**：每个步骤必须包含
-**Artifacts**：该步骤产生的数据
-**Human checkpoint**：需要暂停等待用户确认
-**Rules**：硬性约束
Prompt Engineering — 基于源码的最佳实践
4.1 System Prompt 组装顺序
4.2 高质量 CLAUDE.md 编写模式
💡 结构建议：Tech Stack 声明技术栈，Architecture 列出目录职责，Rules 列出不可违反的约定，用@path引入专项规则。总字符数建议在 40000 以内。
4.3 精细化注入：glob 作用域规则
当某些规则只对特定类型的文件有意义时，用
paths: frontmatter 实现条件注入，节省 token。4.4 记忆系统精确参数
常量 | 值 | 含义 |
ENTRYPOINT_NAME | 'MEMORY.md' | 记忆入口文件名 |
MAX_ENTRYPOINT_LINES | 200 | MEMORY.md 最大行数 |
MAX_ENTRYPOINT_BYTES | 25,000 | MEMORY.md 最大字节数 |
💡 MEMORY.md 是索引文件：每条记忆一行，详情保存在同目录下其他 .md 文件中。
4.5 Agent 记忆作用域详解
Scope | 路径 | 提交 git | 说明 |
user | ~/.claude/agent-memory/{type}/MEMORY.md | 否 | 跨项目通用 |
project | .claude/agent-memory/{type}/MEMORY.md | 可以 | 项目专属，团队共享 |
local | .claude/agent-memory-local/{type}/MEMORY.md | 否 | 机器专属 |
4.6 CLAUDE.md 最佳实践清单
核心原则：技术栈声明明确版本，架构文档列出目录职责，不可破坏的约定，引用专项规则，glob 条件注入，本地覆盖放 CLAUDE.local.md。
常见错误：在用户级写项目特定规则、MEMORY.md 超过 200 行、忘记 .gitignore、Hook 中用模板语法、Skill 文件不在子目录中。
Hook 系统 — 基于源码的精确指南
Hook 是 Claude Code 的自动化引擎。
5.1 27 个 Hook 事件
类别 | 事件名 | 触发时机 |
工具生命周期 | PreToolUse, PostToolUse, PostToolUseFailure | 工具调用前、成功后、失败后 |
用户交互 | Notification, UserPromptSubmit, Elicitation | 通知、用户提交、模型请求输入 |
会话生命周期 | SessionStart, SessionEnd, Stop, StopFailure | 会话开始/结束 |
子 Agent | SubagentStart, SubagentStop | 子 Agent 启动和结束 |
上下文压缩 | PreCompact, PostCompact | 压缩前后 |
权限 | PermissionRequest, PermissionDenied | 权限请求和拒绝 |
配置/文件 | ConfigChange, FileChanged, CwdChanged | 配置和文件变化 |
5.2 4 种 Hook 类型
- command hook：执行 shell 命令，通过 stdin 接收 JSON
- prompt hook：用 LLM 评估条件（仅 PreToolUse/PostToolUse/PermissionRequest）
- agent hook：运行有工具访问权的子 Agent
- http hook：POST JSON 到远程端点
5.3 Hook stdin/stdout JSON 格式
stdin（Claude Code → Hook）：
stdout（Hook → Claude Code）：
5.4 if 字段 — 权限规则语法过滤器
模式 | 匹配内容 |
"Bash(git *)" | 所有 git 命令 |
"Bash(npm test)" | 仅精确匹配 npm test |
"Write(*.py)" | 写入 Python 文件时 |
5.5 asyncRewake — 异步纠错机制
asyncRewake: true 表示 Hook 在后台运行，当进程以 exit code 2 退出时，自动唤醒模型修复。5.6 源码验证的 Hook 配置示例
自动格式化、异步 Lint + asyncRewake、提交前安全扫描、记录 Bash 命令、Python 文件后运行测试、会话结束通知 — 详见各示例代码块。
5.7 7 步 Hook 验证流程
- Dedup 检查
- 构建命令（用 jq 提取，不用 xargs）
- 管道测试
- 写入 JSON
- 验证语法
- 实际触发验证
- 交接
⚠️ settings.json 中的 JSON 语法错误会静默禁用该文件的所有配置！
提高写代码能力 — 配置优化
6.1 模型选择策略
模型 | 适用场景 |
opus | 复杂架构设计、深度推理 |
sonnet | 日常编码、主开发工作 |
haiku | 快速搜索、轻量 Agent、只读探索 |
6.2 omitClaudeMd 优化
适合只读搜索/分析 Agent、安全审计 Agent、格式检查 Agent。
6.3 disallowed-tools 黑名单优于 tools 白名单
当 Claude Code 增加新工具时，Agent 自动获得访问权限。
6.4 TDD 工作流 — Agent + Hook 联动
将 TDD Agent 与 PostToolUse Hook 结合，实现每次代码写入后自动运行测试。
6.5 并行代码审查 — 三 Agent 模式
- 代码复用审查 Agent
- 代码质量审查 Agent
- 效率审查 Agent
6.6 CLAUDE.md 编码标准注入
包括 Immutability、Error Handling、File Size、Functions、Input Validation、Security 等标准。
金融研究实战
7.1 金融研究 Agent
使用
memory: project 持久化分析结论，model: opus 获得最深推理能力。7.2 /analyze-stock Skill
6 步完整流程：Data Collection → Technical Analysis → Fundamental Analysis → Risk Assessment → Investment Thesis → Report Generation
7.3 多 Agent 市场研究工作流
并行三维度：Macro Analysis + Sector Analysis + Sentiment Analysis
7.4 /portfolio-analysis Skill
5 步流程：Load Portfolio → Risk Metrics → Diversification Analysis → Performance Attribution → Recommendations
数据分析实战
8.1 数据分析 Agent
使用
memory: local 保护隐私，max-turns: 40 支持复杂多步探索。8.2 /eda Skill
6 步 EDA 流程：Load → Data Quality → Distribution → Correlation → Outlier Detection → Report
8.3 数据清洗 Skill
6 步清洗流程：Profile → Missing Values → Fix Types → Remove Duplicates → Handle Outliers → Save Output
8.4 SQL 分析 Skill
5 步 SQL 流程：Load Data Source → Understand Question → Write SQL → Validate → Save Results
8.5 Hook：Python 语法验证（asyncRewake 模式）
💡 语法正确 → exit 0 → 静默通过。语法错误 → exit 2 → asyncRewake 唤醒 Claude 自动修复。
8.6 完整数据分析工作流
- 用户输入：
/eda ./data/sales.csv
- Skill 触发：EDA Skill 加载
- Agent 执行：数据分析 Agent 接管
- Hook 监控：Python 语法验证自动运行
- 自动修复：asyncRewake 唤醒修复
- 输出：report.md + PNG 图表
💡 设计小结：memory: local保护隐私；max-turns: 40支持复杂探索；每个 Skill 步骤都有 Success criteria；asyncRewake Hook 形成静默自修复闭环。