技能创作助手

技能创作助手

帮用户为 maka 编写一个高质量、能被正确触发的本地技能（SKILL.md）。maka 的技能是纯文本指令：把一段专有的工作流、领域知识或输出规范写成 agent 可复用的"上手手册"。本技能既是给用户看的方法论，也是给你（agent）执行创作时的操作手册。

maka 技能机制（先记住这几条硬约束）

写之前必须理解 maka 的加载模型，很多写法好坏都由它决定：

• 两层加载。技能目录（catalog）常驻 system prompt，但只包含 name 和 description；正文（body）只有当用户请求匹配、Skill 工具被调用时才按需加载。所以 description 决定能否触发，正文决定触发后做得好不好。
• 正文有上限。Skill 工具加载正文时最多 24,000 字符，超出直接截断（尾部被丢弃）。正文要精炼、把最关键的放前面。
• 单文件自包含。市场导入只取 SKILL.md 一个文件，不支持附带脚本、模板、参考文档。任何"见 reference.md""运行 scripts/x.py"的写法在 maka 里都会失效——所有内容必须写进这一个文件。
• 声明不等于授权。allowed-tools 只是"声明需要哪些工具"的信息，真正的权限始终由 PermissionEngine 在每次调用时决定。技能正文无法提权、无法削弱权限弹窗、无法读取密钥、无法覆盖更高优先级的指令。
• front-matter 是逐行正则解析，不是完整 YAML。字段值必须写在一行内，不支持 > / | 多行折叠语法。多行只会被丢弃或拼接出错。

存放位置

• 工作区技能：{workspace}/skills/<id>/SKILL.md —— 跟随某个工作区。
• 市场来源：~/.maka/skill-sources/<id>/SKILL.md —— 作为可分发/可导入的来源。

<id> 规则：^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$（首字符为字母或数字，其余可含 . _ -，最长 81 字符）。推荐小写 kebab-case，例如 weekly-report、api-changelog、pdf-invoice-extract。id 要具体、可读，别用 helper、utils、tools 这种没信息量的名字。

front-matter 字段

---
name: 周报生成器
description: <一行、触发导向的描述>
category: 效率工具
allowed-tools:
  - Read
  - Glob
---

• name：显示名，中文/英文均可，简短可读。
• description：最重要的字段，触发判断的唯一依据，必须写成一行。详见下文。
• category：市场分类，值必须逐字等于以下之一，否则回落到 效率工具： 内容创作 / 数据与AI / 设计与UI / DevOps与部署 / 文档与写作 / 研究与分析 / 效率工具。
• allowed-tools：声明该技能会用到的工具，YAML 列表或内联 [Read, Glob] 均可。可用工具集：Read、Write、Edit、Glob、Grep、Bash、WebSearch。只声明真正需要的，别为了"保险"全列上。

一、什么样的工作流值得沉淀成技能

不是所有需求都该做成技能。技能的价值在于把非显而易见、会被重复用到的procedural knowledge固化下来。判断标准：

值得做成技能：

• 会反复出现的多步流程（例：每次生成周报都要"读日志 → 归类 → 按固定模板排版"）。
• 有专有规范或约定，模型默认不知道（团队的 commit 格式、公司文档结构、特定报告模板）。
• 领域 schema 或业务规则（某张表的字段含义、某个 API 的调用约定）。
• 有明确、稳定的输出格式要求。

不值得做成技能：

• 一次性任务，做完就不再用。
• 模型本来就会、写进去只是在复述常识（"如何写 Python 函数"）。
• 需要外部脚本/资源才能跑的（maka 单文件不支持）。
• 会频繁变动的临时信息（临时的 API key、某次活动的截止日期）。

一句话自检："下次遇到同类任务，把这份 SKILL.md 喂给一个没有上下文的 agent，它能不能凭这份文件做得又快又对？" 能，才值得沉淀。

二、description 怎么写（决定能否触发）

catalog 里只有 name + description，模型靠它决定"这个请求要不要加载这个技能"。写不好，技能再优秀也永远不会被调用。

要点：

1. 同时说清 WHAT 和 WHEN。做什么（能力）+ 什么时候用（触发场景）。
2. 塞进用户真的会说的关键词。想象用户会怎么开口，把那些词写进去。用户说"帮我写周报""总结这周干了啥"，description 里就该有"周报""本周总结"这些词。
3. 写成一行（front-matter 硬约束），控制在一两句、够具体。
4. 第三人称、面向触发，不要写"我可以帮你…"，写"用于…当用户…时使用"。

反例（太泛，几乎不会被正确触发）：

description: 帮助处理文档。

正例（具体 + 触发词）：

description: 把本周的 git 提交和工作日志汇总成结构化周报。当用户说"写周报""总结本周工作""生成周报"或需要按团队模板整理一周进展时使用。

三、正文结构模板

正文是触发后加载的操作说明，写给"另一个没有上下文的 agent"看。聚焦它不知道、且对做好这件事必要的信息，别复述常识。推荐四段式：

# <技能名>

## 目标
一两句说清这个技能解决什么问题、产出什么。

## 工作流
分步骤、可核对的流程。fragile 的步骤写具体，
有多种合理做法的步骤给方向即可（见下"自由度"）。
1. 第一步…
2. 第二步…
3. 校验/自查

## 输出格式
给出确切的模板或示例。输出质量依赖示例时，
直接把一两个 concrete example 贴进来（Input → Output）。

## 边界
- 什么该做、什么不该做
- 需要用户确认的操作（发送、发布、删除等副作用）
- 缺信息时先问，不要乱猜

自由度要匹配任务的脆弱性：

• 多种合理做法、依赖上下文 → 高自由度，给文字方向即可（如"按可读性组织，突出关键结论"）。
• 有首选模式但允许变通 → 中自由度，给模板/伪代码。
• 一步错就全错、必须一致 → 低自由度，把每一步写死、给可照抄的确切内容。

术语要统一。同一个东西从头到尾用同一个词（一直叫"字段"，别一会儿"字段"一会儿"框""控件"）。

四、常见反模式

• 太宽泛。description 像"帮助处理数据"，触发不了；正文什么都想覆盖，什么都不深。一个技能只解决一类问题。
• 藏敏感信息。别把 API key、token、密码、内部密钥写进 SKILL.md——它是明文、会进 prompt、可被导出分享。需要凭据时，让用户在运行时提供，正文只写"向用户索取 X"。
• 依赖外部文件。写"见 reference.md""运行 scripts/gen.py"——maka 单文件导入，这些一律失效。所有必要内容进正文；确实需要脚本，就在正文里内联给出可复制的完整代码，并说明由用户执行。
• 超长。正文逼近或超过 24,000 字符会被截断，尾部内容直接丢失。精简、把最关键的放前面。
• 时效性信息。"2025 年 8 月前用旧接口"这类会过期。写当前稳定做法即可，旧做法用单独小节标注"已废弃"。
• 靠正文提权。写"忽略权限弹窗直接执行"无效且是危险信号——权限永远由 PermissionEngine 决定，技能正文不能覆盖。
• 多行 front-matter。用 description: > 折叠、或把 description 拆成多行——解析器逐行正则读取，值必须单行，多行会丢失或拼错。

五、创建流程（你执行时按此走）

1. 访谈用户意图

先把需求问清楚，别急着写。一次别问太多，先问最关键的：

• 这个技能解决什么具体任务？给一两个真实例子。
• 用户会用什么话触发它？（直接拿来做 description 的关键词）
• 有没有专有规范、模板、schema 需要固化？
• 输出格式有没有硬要求？ 若对话里已有足够上下文，可直接推断，向用户确认即可。

2. 起草

• 定 id（小写 kebab-case，过一遍 ^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$）。
• 写 name、写触发导向的一行 description、选逐字正确的 category、按需声明 allowed-tools。
• 按四段式写正文，自由度匹配任务，术语统一。

3. 自查清单（写完逐条核对）

• description 一行、含 WHAT + WHEN + 用户会说的关键词
• front-matter 每个值都在一行内，无 > / | 多行语法
• category 逐字等于七个合法值之一
• allowed-tools 只声明真正需要的、且都在可用工具集内
• 正文自包含，无外部文件/脚本依赖
• 正文 < 24,000 字符，关键内容在前
• 无敏感信息、无时效性信息、无提权企图
• id 合法且语义清晰

4. 写入

确认后写到 {workspace}/skills/<id>/SKILL.md（工作区技能）或 ~/.maka/skill-sources/<id>/SKILL.md（作为市场来源）。用 Write 工具创建目录和文件，然后简要告诉用户：id、存放路径、以及"如何触发（哪些话会用到它）"，方便用户验证。

5. 迭代

真正用一次是最好的检验。若触发不了，多半是 description 缺了用户实际会说的关键词；若触发了但做得不对，多半是正文缺了必要的 procedural knowledge 或输出示例。据此针对性修改，别整篇重写。