技能

技能配置指南

本指南介绍如何在 Tentarc 中创建和配置技能。

什么是技能？

技能是扩展 Claude 特定任务能力的专用指令。它使用与 Claude Code SDK 完全相同的 SKILL.md 格式——使技能在两个系统之间完全兼容。

要点：

技能通过斜杠命令调用（例如 /commit、/review-pr）
技能可以通过文件模式（globs）自动触发
技能可以预先批准特定工具无需提示即可运行
SKILL.md 格式与 Claude Code 内部使用的格式完全相同

与 Claude Code SDK 格式相同

Tentarc 使用与 Claude Code SDK 完全相同的 SKILL.md 格式。这意味着：

格式兼容：任何为 Claude Code 编写的技能都可以在 Tentarc 中使用
相同的 frontmatter 字段：name、description、globs、alwaysAllow
相同的内容结构：包含 Claude 指令的 Markdown 正文

Tentarc 额外提供：

可视化图标：在 UI 中为每个技能显示自定义图标
工作区组织：技能按工作区划分
UI 管理：通过界面浏览、编辑和验证技能

技能优先级

当调用技能时（例如 /commit）：

首先检查工作区技能 - 如果 ~/.tentarc/workspaces/{id}/skills/commit/SKILL.md 存在，则使用它
SDK 技能作为备用 - 如果不存在工作区技能，则使用内置 SDK 技能

这允许你：

覆盖 SDK 技能 - 创建相同 slug 的工作区技能以替换内置行为
扩展 SDK 技能 - 在自定义技能中引用 SDK 行为并添加工作区特定指令
创建新技能 - 添加 SDK 中没有的全新技能

技能存储

技能以文件夹形式存储：

~/.tentarc/workspaces/{workspaceId}/skills/{slug}/
├── SKILL.md          # 必需：技能定义（与 Claude Code SDK 格式相同）
├── icon.svg          # 推荐：UI 显示的技能图标
├── icon.png          # 替代：PNG 图标
└── (other files)     # 可选：其他资源

SKILL.md 格式

格式与 Claude Code SDK 技能完全相同：

---
name: "技能显示名称"
description: "技能列表中显示的简短描述"
globs: ["*.ts", "*.tsx"]     # 可选：触发技能的文件模式
alwaysAllow: ["Bash"]        # 可选：始终允许的工具
---

# 技能指令

你的技能内容放在这里。当技能激活时，
这些内容会被注入到 Claude 的上下文中。

## 指南

- Claude 的具体指令
- 要遵循的最佳实践
- 需要避免的事项

## 示例

向 Claude 展示如何正确执行任务。

元数据字段

name（必需）

技能的显示名称。显示在 UI 和技能列表中。

description（必需）

解释技能功能的简短描述（1-2 句话）。

globs（可选）

glob 模式数组。当正在处理匹配这些模式的文件时，技能可能会被自动建议或激活。

globs:
  - "*.test.ts"           # 测试文件
  - "*.spec.tsx"          # React 测试文件
  - "**/__tests__/**"     # 测试目录

alwaysAllow（可选）

当此技能激活时自动允许的工具名称数组。适用于需要特定工具无需提示的技能。

alwaysAllow:
  - "Bash"                # 允许 bash 命令
  - "Write"               # 允许文件写入

创建技能

1. 创建技能目录

mkdir -p ~/.tentarc/workspaces/{ws}/skills/my-skill

2. 编写 SKILL.md

---
name: "代码审查"
description: "从质量、安全性和最佳实践角度审查代码变更"
globs: ["*.ts", "*.tsx", "*.js", "*.jsx"]
---

# 代码审查技能

审查代码时，关注以下方面：

## 质量检查
- 一致的代码风格
- 清晰的命名约定
- 适当的抽象

## 安全检查
- 输入验证
- 认证/授权
- 敏感数据处理

## 最佳实践
- 错误处理
- 性能考虑
- 测试覆盖率

3. 添加图标（重要）

每个技能都应该有一个与其功能相关的图标。这有助于用户在 UI 中快速识别技能。

图标要求：

文件名：必须是 icon.svg、icon.png、icon.jpg 或 icon.jpeg
格式：推荐 SVG（可缩放，任何尺寸都清晰）
尺寸：PNG/JPG 至少 64x64 像素

如何获取图标：

搜索在线图标库：
- Heroicons - MIT 许可
- Feather Icons - MIT 许可
- Simple Icons - 品牌图标（git、npm 等）

使用 WebFetch 下载：

# 找到合适的图标 URL 并下载
WebFetch 获取 SVG 内容，然后保存到 icon.svg

匹配技能用途：
- Git/commit 技能 → git 图标或 commit 图标
- 测试技能 → 勾选或试管图标
- 部署技能 → 火箭或云图标
- 审查技能 → 放大镜或眼睛图标

4. 验证技能

重要：创建或编辑技能后始终进行验证：

skill_validate({ skillSlug: "my-skill" })

验证内容：

Slug 格式（小写、字母数字、仅允许连字符）
SKILL.md 存在且可读
YAML frontmatter 有效
必需字段存在（name、description）
内容非空
图标格式（如果存在）

技能示例

提交消息技能

---
name: "提交"
description: "创建格式规范的 git 提交消息"
alwaysAllow: ["Bash"]
---

# 提交消息指南

创建提交时：

1. **格式**：使用约定式提交
   - `feat:` 新功能
   - `fix:` Bug 修复
   - `docs:` 文档
   - `refactor:` 代码重构
   - `test:` 添加测试

2. **风格**：
   - 主题行保持在 72 字符以内
   - 使用祈使语气（"Add feature" 而不是 "Added feature"）
   - 解释为什么，而不是什么（diff 显示了什么）

3. **共同作者**：
   始终包含：`Co-Authored-By: Claude <noreply@anthropic.com>`

推荐图标：来自 Heroicons 或 Simple Icons 的 Git commit 图标

团队规范技能

---
name: "团队规范"
description: "执行团队编码约定和模式"
globs: ["src/**/*.ts", "src/**/*.tsx"]
---

# 团队编码规范

## 文件组织
- 每个文件一个组件
- 测试与源文件放在一起
- 使用桶导出（index.ts）

## 命名约定
- 组件：PascalCase
- Hooks：camelCase 加 `use` 前缀
- 常量：SCREAMING_SNAKE_CASE

## 导入顺序
1. 外部包
2. 内部包（@company/*）
3. 相对导入

推荐图标：剪贴板列表或清单图标

覆盖 SDK 技能

要自定义内置 SDK 技能（如 /commit）：

创建 ~/.tentarc/workspaces/{ws}/skills/commit/SKILL.md
编写自定义指令
添加图标
运行 skill_validate({ skillSlug: "commit" })

你的技能将代替 SDK 的内置版本使用。

这适用于：

添加团队特定的提交消息格式
执行项目特定的编码标准
为你的代码库自定义审查标准

最佳实践

具体明确：给 Claude 清晰、可操作的指令
包含示例：展示预期的输出格式
设定边界：解释不要做什么
保持专注：一个技能 = 一个特定任务或领域
添加相关图标：使技能在 UI 中易于识别
始终验证：创建或编辑后运行 skill_validate

故障排除

技能未加载：

检查 slug 格式（小写、字母数字、仅连字符）
验证 SKILL.md 存在且可读
运行 skill_validate 获取详细错误

技能未触发：

检查 glob 模式是否匹配你的文件
验证技能在正确的工作区中

图标未显示：

使用支持的格式：svg、png、jpg、jpeg
文件必须命名为 icon.{ext}（不是 my-icon.svg）
检查图标文件是否损坏
对于 SVG，确保 XML 结构有效