# CLAUDE.md
- always-on context
- 启动时不同 level 的 CLAUDE.md 会同时加载，越具体的指令优先级越高。
----
# Skills
- Reuseable instructions，knowledge or workflows
- 跨 contexts 可共享
- context cost
- loaded on demand，session 启动时只加载 description
- ==Full content== on use，使用加载全文到 conversation
- user-only skills (`disable-model-invocation: true`)，只在主动调用时才加载
- subagents：
- skills passed to a subagent are ==fully preloaded== into its context at launch (subagents don’t inherit skills from the main session)
## Bundled skills
- 内置的 skills
| Skill | Purpose |
| --------------------------- | ------------------------------------------------------------------ |
| `/batch <instruction>` | 组织大规模的变更，并行执行。 |
| `/claude-api` | 加载 claude API reference |
| `/debug [description]` | 为当前 session 开启 debug 日志 |
| `/loop [interval] <prompt>` | 定期重复执行一个 prompt<br>`/loop 5m check if the deploy finished` |
| `/simplify [focus]` | reivew 最近更改的文件，并修复发现的问题。<br>`/simplify focus on memory efficiency` |
## Where skills live
### Locations
| Location | Path | Applies to |
| -------- | ---------------------------------------- | ------------ |
| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | 本机所有项目 |
| Project | `claude/skills/<skill-name>/SKILL.md` | 仅限当前项目 |
| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | 当启用 plugin 时 |
- 名字冲突后的优先级：
- personal > project
- plugin skills 使用 `plugin-name:skill-name`，不会冲突
### Nested directories
- Automatic discovery from **nested directories**
- 当在子目录中处理文件时，Claude Code 会自动从嵌套的 `.claude/skills/`目录中发现技能。
- 例如，正在编辑 `packages/frontend/` 中的文件，Claude Code 也会在 `packages/frontend/.claude/skills/` 中查找技能。
- skill directory：
```
my-skill/
├── SKILL.md # Main instructions (required)
├── template.md # Template for Claude to fill in
├── examples/
│ └── sample.md # Example output showing expected format
└── scripts/
└── validate.sh # Script Claude can execute
```
### Additional directories
- 通过 `--add-dir` flag 添加的附加目录，Claude Code 会自动发现其下的 skills，并且支持实时编辑 skill。
- 其他配置则不会从 additional directories 加载，如 subagents，commands 和 output styles。
## Configure skills
### Types of skill content
- skill content 的类型：
- **Reference content**：添加知识到 context，例如
- api-conventions：告诉 Claude 当编写 API 时应当遵守什么规则。
- **Task content**：给定步骤，完成某个动作/任务，例如
- deploy：完成部署任务
```markdown
---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation
```
### Frontmatter reference
#### YAML frontmatter field
- 除了 ==description== 推荐填写，其他都可忽略
| Field | Description |
| ------------------------ | ----------------------------------------------------------------------- |
| name | skill name，忽略则使用目录名字 |
| description | skill的功能及何时使用它。<br>忽略则使用 body 的第一个段落。 |
| argument-hint | autocomplete 时展示期望的参数 |
| disable-model-invocation | true 表示 Claude 不会自动调用，只能手动调用<br>同时 description 也==不会放入 context== |
| user-invocable | false 表示从 `/` menu 隐藏，适用于非 action 类型的 skills（如 backgroud knowledge） |
| allowed-tools | 不需要询问，可使用的 tools 列表，空格分割 |
| model | skill active 时使用的 model |
| effort | low, medium, high, max；复杂的问题使用更高的级别。<br>级别越高：思考能力越强，但越慢且token消耗越大 |
| context | 设置为 `fork` 时以 subagent 的形式隔离运行 |
| agent | 当设置 `context: fork` 时，使用何种 subagent type |
| hooks | 在 skill 内定义 hooks，作用域仅限该 skill |
| paths | 限制 skill 仅在这些目录下工作时才激活。<br>格式：Glob patterns；逗号分隔的 string 或者 yaml list |
| shell | `` !`command` `` 和 ` ```! ` blocks 使用的 shell。<br>例如 bash 或者 powershell。 |
#### **Available string substitutions**
- 支持对 skill content 中的动态变量进行替换
| Variable | Description |
| ---------------------- | ----------------- |
| `$ARGUMENTS` | 调用 skill 时传入的所有参数 |
| `$ARGUMENTS[N]` | 第N个参数，0 起始 |
| `$N` | 同上，例如 `$0`为第一个参数 |
| `${CLAUDE_SESSION_ID}` | - |
| `${CLAUDE_SKILL_DIR}` | `SKILL.md`所在的目录 |
- 参数支持 shell-style quoting
- 例如： `/my-skill "hello world" second`，第一个参数为 `hello world`
- 如果 `SKILL.md`中没有 `$ARGUMENTS`，则会在内容后面==追加== `ARGUMENTS: <value>`，以便让 Cluade 知道你传入了什么参数。
### Add supporting files
- 在 SKILL.md 引用文件，按需加载。
> Keeps `SKILL.md` focused on the essentials while letting Claude access detailed reference material only when needed
### Control who invokes a skill
| Frontmatter | You can invoke | Claude can invoke | Description 是否在 context 中 |
| -------------------------------- | -------------- | ----------------- | ------------------------- |
| (default) | ✅ | ✅ | ✅ |
| `disable-model-invocation: true` | ✅ | ❌ | ❌ |
| `user-invocable: false` | ❌ | ✅ | ✅ |
- full skill loads when invoked
### Skill content lifecycle
- 当调用 Skill 后，`SKILL.md` 的内容将进入 conversation，并在整个 session 期间一直保留。
- Claude code 后续并不会再次读取 `SKILL.md`。
- [ ] ❓带参数的 skill 是怎么处理的？
- Auto-compaction 后重新加载最近调用的 skill。
## Advanced patterns
### Inject dynamic context
- ``` !`<command>` ``` 语法将命令执行的结果填充后，再将 skill content 发送给 Claude。
- 多行命令使用 \`\`\`!
- 禁用：
- settings 中设置 `"disableSkillShellExecution": true`
- 命令执行结果将会被替换为 `[shell command execution disabled by policy]`
### Restrict Claude’s skill access
- 默认可以调用所有未设置 `disable-model-invocation: true` 的 skills。
- 通过 permissions rules 控制可以调用的 skills
- 禁用所有 skills：添加 `Skill` 到 deny rules
- 允许/禁用特定的 skill
- `Skill(commit)`
- exact match
- `Skill(review-pr *)
- prefix match with any arguments.
## Troubleshooting
- Skill descriptions are cut short
- 如果 skill 过多，descriptions 可能会被缩短
- budget：context window 的 1%，最低 8000字符
- 通过 `SLASH_COMMAND_TOOL_CHAR_BUDGET` 环境变量调整
----
# Subagent
- 隔离：
- 独立的 **context**，跟 main conversation/session 分离，工作完成后只将 summary 返回，不会污染 main session 的 context。
- 典型场景：不关心中间结果
- 独立的配置：
- 模型
- 权限
- tool access
- Claude uses each subagent’s ==description== to decide when to delegate tasks.
## Built-in subagents
- Subagents ==只==接收它的 body 作为 system prompt（外加一些基本的环境信息如工作目录），而非 full Claude Code system prompt.