| name | create-skill |
| description | Create or refine a concise, locally maintained Codex skill. Use when the user wants to turn a repeated workflow into a reusable skill, or update an existing skill from recent feedback. Does not create TMA agents; for TMA collaboration skills, use tma-skill-creator.
|
| metadata | {"short-description":"创建/改进技能"} |
create-skill — 创建 / 改进普通 Skill
触发时机
- 创建：用户想把某个手动流程、反复交互方式或固定任务沉淀成 skill。
- 改进：用户想根据最近一次使用中的反馈，更新已有 skill。
如果任务是 tmux multi-agent / TMA 协作流程，改用 tma-skill-creator。本 skill 只处理普通 Codex skill，不创建 TMA Agent。
背景
create 模式默认安装到 $HOME/deploy/configs/llm/skills/<skill-name>；如果用户提到 farside、聊天/个人知识库相关流程，或明确要求放进 farside，则安装到 $HOME/farside/llm/skills/<skill-name>。
refine 模式优先编辑已有 skill 本体：$HOME/deploy/configs/llm/skills/<target>/SKILL.md 或 $HOME/farside/llm/skills/<target>/SKILL.md。如果入口来自 merged-skills，先用 readlink 找真实目录；如果目标目录或 SKILL.md 本身是 symlink，不要修改。
当用户以创建形式调用某个 skill 名称，但该 skill 已经存在（任一安装根目录存在 SKILL.md，或 merged-skills/<name> 能解析到真实 skill 目录）时，直接进入 refine 模式，不要重新创建、覆盖或报“已存在”后停下。只有同名入口指向不明、目标目录是 symlink、或用户明确要求改安装位置但现有入口冲突时，才停下来说明冲突。
核心判断
创建或 refine skill 时，除了任务、背景定义外，只重点写两类东西。其他尽量保持简略，不要把一次性细节、长解释或模型本来就懂的常识塞进 skill。
推荐结构只是候选清单，不是必须填满的模板。不要因为结构里有“输出”“验证”“约束”等小节，就替用户补写没有反馈支撑的输出格式、约束或验证步骤；只有当这类内容确实来自用户意图、最近反馈或稳定提效需求时才保留。
成品 skill 面向未来执行这个任务的 Agent，不是面向“正在创建 skill 的 Agent”。创建过程里的元说明、取舍理由和自我提醒不要写进成品 skill；只保留未来执行时真正需要遵守的触发条件、步骤、输出或约束。
创建或 refine 时，不要把一次任务 prompt、一次产物结构、一次成功输出、或某个具体案例里的做法自动提升为 skill 的长期规则。只有能明确对应用户反馈、反复出现的问题、或稳定提效需求时，才写入成品 skill。
如果用户指出某条新增规则“你本来已经做对了，不需要写进 skill”，要把它当作过度沉淀的负反馈：删除这条规则，并在之后避免把模型已经稳定具备的常规判断写入 skill。
刚创建完某个 skill 后，如果用户继续围绕同一个 skill 提反馈、要求删减、泛化、改口径或补充偏好，默认这是 refine 同一个 skill；不要再按 create 流程处理，也不要把上一版中的具体项目结论当成长期规则保留。这类连续 refine 反馈也是优化 create-skill 本身的重要材料；当用户要求改进 create-skill 时，优先回看这些反馈暴露出的创建流程问题。
写 skill 前先判断这个 skill 的主要价值属于哪一类：
- 流程型：价值在稳定操作顺序、关键命令、外部工具调用、安装/验证步骤。只有这类 skill 才需要
执行步骤。
- 输出型：价值在最终产物的语义、结构、口吻、字段定义或判断标准。优先写
目标 和 输出要求，不要把模型本来能做的分析、归纳、抽象动作写成步骤。
- 约束/风格型：价值在避免跑偏、统一偏好或表达方式。优先写
目标、规则 或 约束，少写流程。
章节按语义职责划分，不按模板硬拆。比如 输出语义约束 和 输出格式 如果都在定义最终产物，就合并成 输出要求；验证 如果只是重复输出要求，就删掉或并入输出要求。每个章节必须承担一个不同职责。
动手创建或修改 skill 文件前，先简短说明计划修改什么；每条计划都要指明它基于本 skill 的哪类准则（意图约束或提效提示），以及对应的用户反馈或观察依据。说不清依据的改动不要做。
1. 意图约束
当 Agent 会做错，需要用户反馈纠正时，要从用户交互中推断背后的真实意图，并改写成下次同类任务也适用的约束。
- 不要只复制用户原话；要总结“用户为什么纠正”。
- 不要写一次性事实、路径、论文名、项目名、实体名或临时结论；如果这些只是本次案例的载体，要抽成跨场景规则。
- 成品 skill 里不要写死本机绝对路径；需要路径时优先使用
$HOME、相对路径、安装根变量，或描述可发现方式。只有用户明确要求保留某个绝对路径，或该路径本身是稳定外部接口时才写绝对路径。
- 不要把“不要在 skill 里写死某 repo 的细节”这类创作期提醒留在成品 skill；如果需要表达成品规则，直接写执行时要做什么。
- 优先落到触发时机、执行边界、输出格式或禁止事项中。
- 只有确实跨步骤通用时，才写成全局规则。
例子：
- 用户说：“这个 skill 不应该每次都问我，能从上下文推断就推断。”
- 写进 skill 时应变成：缺失参数优先从当前对话和本地文件推断；只有推断会导致高风险写入或不可逆操作时才询问。
2. 提效提示
当 Agent 不一定会做错，但会反复走弯路、重复探索或低效等待时，可以记录提示，让下次更快。
- 只记录能稳定节省时间的信息。
- 不要因为一次偶然情况增加复杂流程。
- 提示要短，最好直接落到执行步骤里。
- 对命令、文件位置、验证方式可以写得具体；对判断结论要保持可泛化。
候选结构
这些章节只是候选，不是模板。先选章节，再写内容；不需要的章节直接省略。
---
name: <skill-name>
description: >
<这个 skill 做什么；什么时候触发>
metadata:
short-description: <简短中文名>
---
# `<skill-name>` — <中文标题>
## 触发时机
<任务域和触发语>
## 目标
<这个 skill 要稳定达成的效果>
## 输入
<用户需要给什么；哪些内容可从上下文推断>
## 执行步骤
<仅当存在非显然的稳定流程、关键命令、外部工具调用或顺序依赖时保留; 如果不写这些执行步骤，模型本身一般也是这么干的，就不用显示写出来>
## 输出要求
<最终产物的语义、结构、字段定义、口吻、格式示例>
## 验证
<仅当存在独立于输出要求的检查方式时保留>
## 约束
<禁止事项、边界、依赖前提>
不需要每个 skill 都完整保留所有小节；没有实际内容的小节直接删掉。
尤其不要为了让 skill 看起来“完整”而补写 执行步骤。如果那些内容只是“如何思考”“如何归纳”“如何把内容放进表格”，通常属于模型本身能力；只保留目标和输出要求即可。
尤其在根据用户反馈 refine 时，优先做减法：删除过度推演出来的小节和规则，只留下本次反馈能解释的意图约束或提效提示。
安装与验证
create 模式：
SKILL_DIR=<install_root>/<skill-name>
mkdir -p "$SKILL_DIR"
ln -s "$SKILL_DIR" "$HOME/deploy/configs/llm/merged-skills/<skill-name>"
test -f "$SKILL_DIR/SKILL.md"
test -L "$HOME/deploy/configs/llm/merged-skills/<skill-name>"
如果 merged-skills 下同名 symlink 已存在，确认它指向 $SKILL_DIR；如果指向不同目录，直接报错，让用户决定覆盖或改名。
refine 模式：
- 不重新安装 skill。
- 小范围修改已有
SKILL.md，除非用户明确要求重写。
- 验证新增内容是否确实对应这次用户反馈里的意图约束或提效提示。
- 最终回复只说明应用了哪些反馈、改了哪些文件、还有什么未决问题。
