技能的工作原理
技能使用渐进式加载来保持上下文精简。打开项目时,Agent 只看到所有技能的名称和描述——每个技能只有几十个字。这是启动时唯一加载的内容。 当你的请求与某个技能的描述匹配时,Agent 激活该技能并加载完整指令。短篇小说创作技能在你写查询信时保持休眠,恐怖小说技能在你做惊悚小说大纲时不会占用上下文。| 级别 | 加载时机 | 内容 |
|---|---|---|
| 元数据 | 始终,启动时 | frontmatter 中的名称和描述 |
| 指令 | 技能触发时 | 完整的 SKILL.md 正文 |
| 支撑文件 | 按需 | 模板、脚本、参考文档 |
技能结构与存储位置
每个技能是一个包含SKILL.md 文件的目录,目录名即为技能名。技能还可以在三个可选子目录中包含支撑文件。
.soloent/skills/ 中。适合与特定项目或类型绑定的能力——基于这个言情系列特定规则构建的技能,或针对当前故事的尺度和叙事风格校准的技能。
技能开关
每个技能都有开关,无需删除文件即可启用或禁用。当前任务不需要某个技能时,禁用它可以让它脱离上下文,避免意外激活。创建技能
SKILL.md 文件由两部分组成:frontmatter(元数据)和指令正文。
name必须与目录名完全一致description描述何时触发此技能,而不是它能做什么(不超过 1,024 个字符)

获取完整的 english-short-story 技能——点击展开并复制
获取完整的 english-short-story 技能——点击展开并复制
三种常见技能类型
类型一:检查清单型
适合在固定节点一次性核验多项标准,防止漏项。例如每章写完后的提交前检查:类型二:工作流型
适合有明确步骤顺序、执行前需要确认的操作。类型三:领域专家型
适合让 Agent 按专家经验工作、而不是凭感觉乱猜的情况。例如写作卡壳时的诊断技能:完整案例:作品总结
这是一个领域专家型技能。 它定义了获取内容路径(脚本按需提取章节)、专业定义(docs/ 中存放章节识别模式)和固定输出格式(templates/ 中的笔记模板)——这三个要素正是领域专家型技能的典型结构。
此技能从本地书籍文件中提取结构化笔记——章节摘要、关键观点、金句——并保存为格式化 Markdown。
目录结构
为什么需要脚本
书籍很长。把整本书加载到上下文中来提取章节结构既浪费又缓慢。预处理脚本解决了这个问题:info命令 — 读取前 50 行,识别书名、编码和总行数chapters命令 — 扫描章节标题并返回行号,无需读取全文extract命令 — 只读取某一章的内容,让 Agent 逐章处理
为什么需要 docs 文件
中英文书籍的章节标题格式差异很大。与其把所有识别模式嵌入SKILL.md,不如将它们存放在 docs/chapter-patterns.md 中。Agent 需要识别章节边界时读取这个文件,其他时候忽略它。
将参考资料放在 docs/ 中有两个好处:让 SKILL.md 专注于工作流逻辑,同时可以更新模式而不修改主指令。
为什么需要模板
输出格式是固定的:每份读书笔记都遵循相同结构——书籍概览、章节摘要(含关键观点和金句)、全书精华、个人思考。与其在每次提示词中重新说明格式,不如将其存放在templates/note-template.md 中。
第 5 步(最终汇总)运行时,Agent 加载模板并填入占位符。格式每次一致,只需在一处维护。
SKILL.md 如何引用支撑文件
SKILL.md 中的指令明确指向每个支撑文件:
写出有效的技能
description 写”何时用我”,不写”我是干什么的”
这两个听起来差不多,但对触发准确率影响很大。有完整步骤、输入、输出和停止条件
一个技能指令如果只写了流程开头、没有明确的完成标志,Agent 会自行决定什么时候停下来——通常不是你期望的位置。每个步骤都应该有:- 输入:这一步需要哪些上下文或文件
- 输出:这一步产出什么
- 停止条件:什么情况下等待确认,什么情况下继续
正文只放导航和核心约束,大资料拆到支撑文件
SKILL.md 正文控制在 5,000 字以内。如果需要风格参考、识别模式、角色档案等大量资料,放进 docs/ 子目录,在指令里按文件名引用——Agent 需要时才加载,不需要时不占上下文。
按调用频率决定是否开启自动触发
| 使用频率 | 建议策略 |
|---|---|
| 高频(每次会话超过 1 次) | 保持自动触发,优化描述符让触发更准确 |
| 低频(每次会话不超过 1 次) | 关闭自动触发,手动调用,描述符可以脱离上下文 |
| 极低频(每月不超过 1 次) | 移除技能,改为在 SOLOENT.md 中记录文档 |
容易踩的坑
| 问题 | 症状 | 怎么修 |
|---|---|---|
| 描述过于宽泛 | description: help with writing——任何写作请求都能触发 | 收窄到具体场景,加入实际触发短语 |
| 正文过长 | 几百行工作手册全塞进 SKILL.md 正文 | 参考资料拆到 docs/,指令只保留骨架 |
| 一个技能做五件事 | 同一个技能覆盖审稿、续写、大纲、角色设计、诊断 | 拆开,每个领域一个技能,可以单独开关 |
使用他人的技能
不必从头创作每一个技能。技能是自包含的目录——你可以手动安装、从仓库克隆,或以插件形式安装。手动安装
下载或复制技能目录,放置到对应位置:- 全局技能 → 系统级技能目录(在所有项目中可用)
- 项目技能 → 项目内的
.soloent/skills/
通过 git clone
托管在 GitHub 上的公开技能可以直接克隆到技能目录:git pull 拉取最新改动。
通过插件
部分技能作者以打包好的.vsix 扩展文件分发技能。安装扩展后,内置技能自动加载,无需手动放置文件。
故障排除
技能没有按预期激活
技能没有按预期激活
最可能的原因:描述不够具体,或者技能被关闭了。
- 检查技能在 Skills 面板中是否已启用
- 重写
description,加入你实际使用的短语和任务类型——“帮助写作”很少能正确触发;列出具体工作流、输出类型和示例触发语句 - 确认技能目录中有有效的
SKILL.md文件,且包含name和description两个 frontmatter 字段 - 确认 frontmatter 中的
name与目录名完全一致
技能在不需要时反复激活
技能在不需要时反复激活
描述太宽泛了——它匹配了你并不想触发它的请求。
- 把
description收窄,只描述这个技能处理的具体任务 - 不需要某个技能时,在 Skills 面板中关掉它
- 如果多个技能的描述有重叠,分别把每个描述写得更加具体,明确各自的适用范围
技能指令被忽略或只执行了一部分
技能指令被忽略或只执行了一部分
请检查以下常见问题:
- 指令可能超出了上下文限制——把
SKILL.md控制在 5,000 字以内,将参考资料移到docs/子目录 - 某条全局或项目规则可能覆盖了技能的部分行为——检查当前启用的规则是否与技能指令冲突
- 如果技能使用了检查清单,确保每个关键节点都有明确的”等待确认”门控;否则 Agent 会自动推进
- 指令中引用的支撑文件必须存在于指定路径——文件缺失会导致该步骤被静默跳过
支撑文件(模板、docs、脚本)没有被加载
支撑文件(模板、docs、脚本)没有被加载
Agent 只在指令明确引用时才加载支撑文件。
- 确认指令中的文件路径与实际位置一致(例如
templates/chapter-outline.md,而不是chapter-outline.md) - 确认文件位于技能目录下正确的子目录中(
templates/、docs/或scripts/) - 如果
SKILL.md中没有按文件名引用该文件,Agent 就没有理由加载它
项目技能与同名全局技能冲突
项目技能与同名全局技能冲突
项目技能始终优先于同名的全局技能。
- 这是预期行为——如果项目技能处于激活状态,同名的全局技能会被完全忽略
- 如果需要全局技能生效,请重命名或删除项目技能
- 如果两者都需要存在,给它们起不同的名字并更新各自的描述
更多高级技巧
Workflows(工作流)
用工作流文件自动化可重复的多步骤流程
Rules(规则)
将你的写作偏好写入规则,让 Agent 始终用你的风格写作
Rule、Workflow、Skill 怎么选
三种 AI 指令方式各管各的事——了解它们的区别和适用场景