DeepCode
/文档
EN

Agent Skills

概述

适合写成 skill 的内容通常具备以下特点：

  • 会重复使用，例如固定的代码审查流程、发布流程或文档生成流程
  • 需要较长的说明，不适合每次都粘贴到对话中
  • 需要配套资源，例如模板、脚本、schema、示例或参考文档
  • 需要明确触发条件，例如“处理 PDF 表单”或“为本项目生成数据库迁移”

不适合写成 skill 的内容：

  • 一次性的任务要求
  • 当前仓库的短规则，此类内容更适合写入 AGENTS.md
  • 需要实时连接外部系统的能力，此类能力更适合通过 MCP 提供工具

扫描位置

Deep Code 会按以下顺序扫描 skills。相同 name 的 skill 只保留优先级最高的一个。

优先级ScopePath用途
1Project./.deepcode/skills/Deep Code 项目级原生位置
2Project./.agents/skills/项目级跨客户端互操作位置
3User~/.deepcode/skills/Deep Code 用户级原生位置
4User~/.agents/skills/用户级跨客户端互操作位置
5Globalbuilt-inDeep Code 内置 skills

目录结构示例：

.deepcode/
└── skills/
    └── code-review/
        ├── SKILL.md
        ├── checklist.md
        └── scripts/
            └── collect-diff.sh

最小 Skill

每个 skill 必须放在独立目录中，并包含 SKILL.md。

---
name: code-review
description: Review code changes for correctness, regressions, security risks, and missing tests. Use when the user asks for a review, PR review, diff review, or pre-merge check.
---
 
# Code Review
 
Use a code review mindset. Prioritize bugs, behavioral regressions, security issues, and missing tests over style comments.
 
## Workflow
 
1. Inspect the diff and relevant surrounding code.
2. List findings first, ordered by severity.
3. Include file and line references for every finding.
4. If there are no findings, say so and mention residual risks or test gaps.

SKILL.md Frontmatter

Deep Code 会读取 SKILL.md 文件顶部的 YAML frontmatter。

字段必填Deep Code 行为建议
name建议必填作为 skill 的唯一名称。缺失时使用目录名，并把 _ 转成 -。使用小写字母、数字和连字符。保持与目录名一致。
description建议必填用于自动匹配任务，也显示在 /skills 和斜杠菜单中。写清楚 skill 做什么、何时使用、常见触发词。
metadata.allow-implicit-invocation可选设置为 false 时，不参与自动匹配；仍可手动选择。用于只想手动调用的 skill。

示例：

---
name: db-migration
description: Create and review database migrations for this project. Use when the user asks to add columns, change schema, write migrations, or validate rollback behavior.
metadata:
  allow-implicit-invocation: false
---

Deep Code 当前只解释上表中的字段。其他 frontmatter 字段可用于跨客户端互操作或文档说明，但不会自动限制 Deep Code 的工具权限。

写好 description

description 是最重要的发现信号。Deep Code 会在自动匹配阶段只把 skill 的 name 和 description 交给模型判断，因此描述越具体，匹配越可靠。

推荐结构：

<这个 skill 做什么>. Use when <任务类型、文件类型、领域、用户常见说法或触发词>.

好的示例：

description: Extract tables from PDF files, fill PDF forms, and merge documents. Use when working with PDFs, forms, invoices, statements, or document extraction.
description: Generate Lessweb routes, services, and Pydantic request models. Use when editing Lessweb projects, adding @Get/@Post endpoints, configuring IOC modules, or updating OpenAPI output.

避免：

description: Helps with documents
description: Useful project skill
description: Tooling instructions

检查清单：

  • 是否说明了具体能力，而不是只写主题名
  • 是否说明了何时使用，而不是只写结果
  • 是否包含用户可能输入的关键词
  • 是否包含相关文件类型、框架名、命令名或领域名
  • 是否避免覆盖过宽，导致无关任务也触发

Skill 正文结构

SKILL.md 的正文应面向 agent，而不是面向普通读者。写法要直接、可执行、可验证。

推荐结构：

# Skill Name
 
Briefly state what this skill is for.
 
## When to use
 
- Use when ...
- Do not use when ...
 
## Workflow
 
1. Read ...
2. Run ...
3. Edit ...
4. Verify ...
 
## Rules
 
- Preserve ...
- Never ...
- Ask the user when ...
 
## Examples
 
...

写作原则：

  • 使用命令式步骤，例如“Read the schema first”或“Run tests after editing”
  • 把必须遵守的约束写成明确规则
  • 对高风险操作写清楚边界，例如删除文件、迁移数据、发送请求
  • 对常见分支写出决策规则，例如“如果没有配置文件，先搜索默认路径”
  • 避免把大量参考资料全部塞进 SKILL.md

附加资源

一个 skill 可以包含 SKILL.md 之外的文件：

my-skill/
├── SKILL.md
├── references/
│   └── api.md
├── examples/
│   └── request.json
├── scripts/
│   └── validate.py
└── templates/
    └── report.md

如果某些内容会让 SKILL.md 过长或难以阅读，可以放到附加文件中：

  • references/ 放长文档、规范、API 说明
  • examples/ 放输入输出样例
  • scripts/ 放可复用脚本
  • templates/ 放文档或代码模板
  • 在 SKILL.md 中说明什么时候需要使用这些附加文件

示例：

## Workflow
 
1. Read `references/schema.md` before changing generated types.
2. Use `templates/migration.sql` when creating a new migration.
3. Run `python scripts/check_migration.py <file>` before reporting completion.

调用方式

Deep Code 支持自动和手动两种调用方式。

自动调用

每次用户输入后，Deep Code 会根据可用 skills 的 name 和 description 判断哪些 skill 与任务匹配。匹配到的 skill 会被加载到当前会话中。

自动调用规则：

  • 已加载的 skill 不会在同一会话中重复加载
  • metadata.allow-implicit-invocation: false 的 skill 不会自动加载
  • 自动匹配会结合当前 AGENTS.md 指令
  • 如果没有匹配项，则不加载 skill

手动调用

你可以在输入框中使用 / 打开 skills / 命令菜单，选择某个 skill；也可以使用 /skills 查看可用 skills。

常用命令：

命令作用
/打开 skills / 命令菜单
/skills列出可用 skills
/<skill-name>从菜单中选择对应 skill

启用和禁用

使用 settings.json 的 enabledSkills 可以按 skill 名称启用或禁用 skill。

{
  "enabledSkills": {
    "code-review": true,
    "db-migration": false
  }
}

规则：

  • 未配置的 skill 默认启用
  • 设置为 false 会隐藏所有扫描位置中同名的 skill
  • 项目设置会按 skill 覆盖用户设置

更多配置说明请参考 configuration.md。

与 AGENTS.md、MCP 的区别

机制适合放什么不适合放什么
AGENTS.md当前仓库的长期规则、代码风格、测试命令、协作约定可复用的复杂工作流或跨项目工具说明
Agent Skill可复用工作流、领域知识、模板、脚本、参考资料只对当前一次任务生效的临时要求
MCP外部系统能力、实时数据、浏览器、数据库、GitHub 等工具调用纯文本流程说明

常见组合：

  • 把项目规则写进 AGENTS.md
  • 把可复用流程写成 skill
  • 把需要执行外部动作的能力接入 MCP

编写示例：项目发布 Skill

---
name: release-check
description: Prepare and verify a project release. Use when the user asks to release, publish, bump version, update changelog, or run pre-release checks.
---
 
# Release Check
 
Use this skill to prepare a safe release for this repository.
 
## Workflow
 
1. Read `package.json` and the existing changelog.
2. Inspect commits or diffs since the previous release tag.
3. Update version and changelog only when the user explicitly asks.
4. Run the project test and build commands.
5. Report the version, changed files, verification results, and remaining risks.
 
## Rules
 
- Do not publish packages unless the user explicitly asks.
- Do not create or push git tags without explicit approval.
- Preserve existing changelog style.

故障排查

/skills 中看不到 skill

检查：

  1. 目录是否位于 Deep Code 扫描位置之一
  2. 文件名是否为 SKILL.md
  3. SKILL.md 是否在独立 skill 目录中，例如 .deepcode/skills/my-skill/SKILL.md
  4. enabledSkills 是否把该 skill 设置为 false
  5. 是否存在同名 skill 被更高优先级位置覆盖

自动调用不稳定

检查：

  1. description 是否包含清晰的使用场景和触发词
  2. skill 是否过宽，导致模型难以判断边界
  3. 是否设置了 metadata.allow-implicit-invocation: false
  4. 用户请求是否需要更明确地提到该 skill 的领域或文件类型

Skill 内容过长

建议：

  1. 保留 SKILL.md 中的核心流程和规则
  2. 把长文档移到 references/
  3. 把重复命令移到 scripts/
  4. 在 SKILL.md 中说明何时读取相关文件

参考