# Skills 与自学习

Skills 是 DotCraft 让 Agent 复用工作流程的方式：把"怎么做这件事"沉淀为带 frontmatter 的 Markdown 文件，Agent 在遇到匹配场景时主动加载并按其中的步骤执行。Skills 可以系统内置、可以你手写，也可以让 Agent 在成功完成任务后自己保存——而且坏掉时永远可以回到原版。

> 让经验沉淀在工作区里，而不是模型的"印象"里。

## Skills 来源

| 来源 | 路径 | 说明 |
|---|---|---|
| **系统** | DotCraft 安装包内 | 内置 skill，随应用提供，所有工作区共用 |
| **个人** | `~/.craft/skills/` | 用户全局技能，可跨工作区使用 |
| **工作区** | `.craft/skills/` | 当前项目专属技能，跟随仓库走 |
| **插件自带** | `.craft/plugins/<id>/skills/` | 由插件分发的 skill，跟随插件生命周期 |
| **市场安装** | `.craft/skills/<id>/`（带 `.dotcraft-market.json`） | 来自 SkillHub / ClawHub 的第三方技能 |

来源不是默认开关：是否启用由 Skills 管理页面控制；从市场搜到的技能必须先安装才进入本地列表。

## Agent Skill 自学习

`Skills.SelfLearning.Enabled`（默认开启）会让 Agent 看到一个聚合工具 `SkillManage(action, ...)`，用于在当前工作区创建、修补、维护 skill 文件。

```json
{
  "Skills": {
    "SelfLearning": {
      "Enabled": true
    }
  }
}
```

| Action | 必填参数 | 用途 |
|---|---|---|
| `create` | `name`, `content` | 创建新的工作区 skill |
| `patch` | `name`, `oldString`, `newString` | 局部修补 `SKILL.md` 或 supporting file |
| `edit` | `name`, `content` | 完整替换已有工作区 skill 的 `SKILL.md` |
| `write_file` | `name`, `filePath`, `fileContent` | 写入 supporting file |
| `remove_file` | `name`, `filePath` | 删除 supporting file |

`create` 会触发 `kind: skill` 审批，破坏性的 `delete` 也会触发审批；`edit` / `patch` / `write_file` / `remove_file` 不需审批。

| 配置 | 默认 | 说明 |
|---|---|---|
| `Skills.SelfLearning.Enabled` | `true` | 主开关；关闭后 `SkillManage` 不暴露给模型 |
| `Skills.SelfLearning.MaxSkillContentChars` | `100000` | 单个 `SKILL.md` 最大字符数 |
| `Skills.SelfLearning.MaxSupportingFileBytes` | `1048576` | 单个 supporting file 最大字节数 |

### 边界与目录约束

- 自学习只写当前工作区 skill 目录；**系统 skill 与个人 skill 视为只读**——需要修改时由 Agent 创建工作区副本。
- supporting file 只能写在 `scripts/` 或 `assets/` 子目录。
- 工具会拒绝绝对路径和 `..` 路径穿越。

### 适合保存为 skill 的情况

- 完成复杂任务后总结出可复用流程
- 修复了一个以后可能再次遇到的棘手错误
- 用户纠正了 Agent 的做法，并形成了稳定步骤
- 使用已有 skill 时发现其步骤过期、不完整或存在坑点

简单的一次性回答不应保存为 skill。

## 在 Desktop 中搜索与安装

DotCraft 的 Skills 页面同时搜索本地已安装技能和外部技能市场：

![Skills 页面](https://github.com/DotHarness/resources/raw/master/dotcraft/skills.png)

搜索框会同时做两件事：

- 过滤当前已安装的本地技能
- 当有查询词时，搜索 SkillHub 和 ClawHub 的市场结果

来源筛选可切换 `全部 / 系统 / 个人 / 市场`，只影响浏览结果，不改变启用状态。

### 从市场安装

1. 在搜索结果中点击一个市场技能
2. 在详情页阅读 README、描述和来源链接
3. 点击 **Install with DotCraft**
4. DotCraft 会启动一个安装 Agent：检查工作区、系统环境和可用工具，并在发现差异时为本地环境生成优化版本
5. 安装完成后刷新本地技能列表

![Skill market 搜索结果](https://github.com/DotHarness/resources/raw/master/dotcraft/skill-hub.png)

<video controls src="https://github.com/DotHarness/resources/raw/master/dotcraft/skill_variant.mp4" style="width: 100%; border-radius: 8px;"></video>

<p class="caption">Desktop 通过 DotCraft 安装市场技能并生成本地变体</p>

市场技能落地为：

```text
.craft/skills/<skill-name>/
.craft/skills/<skill-name>/.dotcraft-market.json
```

`.dotcraft-market.json` 用来识别来源、版本和更新状态，工作区已存在同名技能时 Desktop 会要求确认后再覆盖。

### Skill Variant：保留原版，叠加优化

通过 **Install with DotCraft** 安装时，Agent 会先保留原始技能再生成针对当前环境的优化版本（Variant），不直接覆盖原版。后续使用时 DotCraft 优先用当前有效 Variant；想回到市场安装时的原始内容，可在 Skills 页面随时恢复。

这样自学习带来的收益保留下来，风险也有清晰的回退路径。

## 启用 / 禁用管理

Skills 页面右上角 **管理** 是批量启用/禁用入口：

1. 点击 **管理**
2. 在管理页搜索已安装技能
3. 用每行右侧开关控制启用状态

管理页只管理已安装到本地的技能，不会去搜索 SkillHub / ClawHub。被禁用的技能不会进入 Agent 上下文，但文件仍保留。

## 内置工作流 skill：`skill-authoring`

启用自学习后，DotCraft 会注入 `skill-authoring` 作为按需参考——告诉 Agent `SKILL.md` frontmatter 要求、action 选择、supporting file 目录约束、常见坑和验证方法。`skill-authoring` 的 `tools: SkillManage` 决定了：自学习关闭时它也不会列入可用 skill 清单。

## 安全与信任

- 系统 skill 与插件自带 skill 默认可信。
- SkillHub / ClawHub 是外部来源，安装前阅读 README 与来源链接，必要时先在分支或受控工作区验证。
- 市场搜索失败或断网时，本地技能搜索和管理仍可继续使用。

## 何时用什么

| 场景 | 推荐 |
|---|---|
| 项目内固定流程（"提交 PR 前必跑 lint+test"） | 工作区 skill，可手写也可让 Agent 创建 |
| 跨项目通用偏好（自己的代码风格） | 个人 skill |
| 受控分发的能力包（含工具 + 多 skill） | 创建 [Plugin](./plugins-tools.md) |
| 想让 Agent 把刚解决的问题沉淀下来 | 启用自学习，让它调用 `SkillManage create` |
| 想用社区已有方案 | Skills 页面市场搜索 + Install with DotCraft |

## 相关入口

- [Plugins 与工具](./plugins-tools.md) — 用插件分发 skills + tools 的能力包
- [项目级工作区](./workspace.md) — `.craft/skills/` 在整体目录中的位置
- [示例与模板](../resources/samples.md) — `dev-guide`、`feature-workflow` 等可复制示例
