Newtouch Code Agent Skills 配置说明

Newtouch Code Agent Skills 配置说明

Agent Skill 用于给 Newtouch Code 增加特定场景的能力说明、操作规范、上下文资料和工具使用流程。适合沉淀团队内部规范，例如发版、代码审查、接口联调、数据库变更、问题排查等。

截图待补充：Newtouch Code 识别并加载 Agent Skill 的界面。

放置位置

当前 Newtouch Code 支持以下 Skill 发现路径。

范围	推荐路径	说明
项目级	.newtouchcode/skills/<skill-name>/SKILL.md	推荐团队共享，随项目提交到 Git
项目级简写	.newtouchcode/skill/<skill-name>/SKILL.md	兼容单数目录
用户级	~/.config/newtouchcode/skills/<skill-name>/SKILL.md	适合个人长期使用
用户级简写	~/.config/newtouchcode/skill/<skill-name>/SKILL.md	兼容单数目录
Agent 生态兼容项目级	.agents/skills/<skill-name>/SKILL.md	兼容通用 Agent Skills 目录
Agent 生态兼容用户级	~/.agents/skills/<skill-name>/SKILL.md	兼容通用 Agent Skills 目录
Claude 兼容项目级	.claude/skills/<skill-name>/SKILL.md	兼容 Claude Code Skills
Claude 兼容用户级	~/.claude/skills/<skill-name>/SKILL.md	兼容 Claude Code Skills

建议 Newtouch Code 自己的文档优先使用以下路径：

.newtouchcode/skills/<skill-name>/SKILL.md
~/.config/newtouchcode/skills/<skill-name>/SKILL.md

项目级 Skill 更适合团队共享，用户级 Skill 更适合个人习惯。

基本目录结构

每个 Skill 使用一个独立目录，目录名建议与 name 保持一致。

.newtouchcode/
└── skills/
    └── release-note/
        ├── SKILL.md
        ├── references/
        │   └── release-template.md
        └── scripts/
            └── collect-changelog.sh

最小结构只需要一个 SKILL.md：

.newtouchcode/
└── skills/
    └── release-note/
        └── SKILL.md

截图待补充：项目中 .newtouchcode/skills/ 的目录结构。

SKILL.md 基本格式

SKILL.md 需要包含 frontmatter，至少包含 name。建议同时填写 description，用于让 Newtouch Code 判断什么时候使用该 Skill。

---
name: release-note
description: 当用户需要生成版本发布说明、整理 changelog、总结提交记录或准备发版文档时使用。
---

# Release Note Skill

## 使用场景

当用户要求生成发布说明、整理版本变更、总结 Git 提交、输出发版公告时，使用此 Skill。

## 工作流程

1. 确认目标版本号和比较范围。
2. 读取 Git 提交记录和变更文件。
3. 按功能、修复、文档、工程化、破坏性变更分类。
4. 输出面向业务或研发的发布说明。
5. 如存在风险或未验证项，需要单独列出。

## 输出要求

- 使用中文。
- 优先面向业务可读性。
- 不暴露内部无关实现细节。
- 风险项单独放在“注意事项”中。

字段说明

frontmatter 支持以下字段：

---
name: skill-name
description: 这个 Skill 什么时候应该被使用
---

字段	说明
name	必填，Skill 的唯一名称。
description	推荐填写，Newtouch Code 会根据它判断是否应该使用该 Skill。
SKILL.md 正文	写具体规则、流程、示例、限制和输出格式。

使用 references 目录

当 Skill 需要较长的背景资料、模板或规范时，不建议全部塞进 SKILL.md。可以放到 references/ 目录中，并在 SKILL.md 中说明何时读取。

.newtouchcode/skills/api-review/
├── SKILL.md
└── references/
    ├── api-style-guide.md
    └── error-code-rules.md

示例：

---
name: api-review
description: 当用户需要审查接口设计、接口文档、错误码或 OpenAPI 定义时使用。
---

# API Review Skill

当审查接口规范时，先阅读：

- `references/api-style-guide.md`
- `references/error-code-rules.md`

重点检查：

1. URL 命名是否符合 REST 风格。
2. 请求参数是否清晰。
3. 响应结构是否统一。
4. 错误码是否可诊断。
5. 是否存在兼容性风险。

使用 scripts 目录

当 Skill 需要固定脚本辅助执行时，可以放到 scripts/ 目录中。

.newtouchcode/skills/db-migration/
├── SKILL.md
└── scripts/
    └── check-migration.sh

示例：

---
name: db-migration
description: 当用户需要创建、审查或验证数据库迁移脚本时使用。
---

# DB Migration Skill

处理数据库迁移时：

1. 检查 SQL 是否可重复执行。
2. 检查是否存在锁表风险。
3. 检查是否有回滚方案。
4. 如需要，运行 `scripts/check-migration.sh` 进行基础校验。

在配置中额外指定 Skill 路径

除默认目录外，也可以在 newtouchcode.jsonc 中配置额外 Skill 来源。

{
  "skills": [
    "./team-skills",
    "~/shared-newtouchcode-skills",
    "https://example.com/newtouchcode/skills/",
  ],
}

说明：

• 本地相对路径基于当前项目目录解析。
• ~/ 会解析到当前用户 home 目录。
• URL 需要提供远程 Skill 索引，通常包含 index.json 和对应的 SKILL.md 文件。

推荐实践

• 项目团队共享的 Skill 放在 .newtouchcode/skills/。
• 个人习惯类 Skill 放在 ~/.config/newtouchcode/skills/。
• description 要写清楚触发场景，不要写得太泛。
• 一个 Skill 只解决一类问题，不要把发版、测试、审查、部署混在一个 Skill 里。
• 大量背景资料放到 references/，避免 SKILL.md 过长。
• 固定命令或检查逻辑放到 scripts/，避免模型每次重新猜命令。
• 团队级 Skill 建议提交到 Git，随项目版本演进。