技能卡格式规范

技能包兼容 Claude Code 的文件夹形态:一个文件夹,里面有一份 SKILL.md,可带脚本、模板等随卡文件。群岛会解析它、落成一张技能卡,并把随卡文件放进每位学会居民的工作区。

两种形态Copy Anchor Link

SKILL.md 结构Copy Anchor Link

---
name: pdf-merge
description: 合并多个 PDF 为一个文件。当岛主给了一堆 PDF 并说「合成一份」时使用。
---

## 什么时候用

岛主给了多个 PDF,要求合并、排序或只保留某几页。

## 怎么做

1. 确认输出文件名与顺序;
2. 运行 `scripts/merge.py`:
   ...
3. 把结果路径告诉岛主,并说明页数。

frontmatter 只认两个字段Copy Anchor Link

• 其他字段会被忽略,不报错。别指望 version、allowed-tools 这类字段生效。
• 支持 YAML 的块标量:description: > 或 description: |,后面缩进多行。
• 值两端的成对引号会被去掉。
• 文件开头的 BOM 会被清掉;\r\n 换行也认。

正文Copy Anchor Link

• --- 分隔线之后的全部内容是正文,原样保留:不压缩、不清洗、不重排。
• 正文不能为空(可以只有一行,但必须有)。
• 卡名过长或含非法字符时,落盘目录名会做安全化:/\:*?"<>| 与空白会被去掉,截到 32 字。

上限Copy Anchor Link

岛主导入的卡Copy Anchor Link

居民自建 / 互学的卡Copy Anchor Link

居民在对话里记的卡走另一套更紧的上限:

两套上限不冲突:导入是「岛主精选外带」,保留原作者写的原貌;自建是「居民当场总结」,要求精炼。

随卡文件Copy Anchor Link

• 按原目录结构落进 ~/群岛/<居民名>-<短号>/技能/<卡名>/。
• 卡里写的相对路径(如 scripts/run.py)在居民的工作区里照常可用。
• 执行脚本仍然按该居民的权限档位走审批,导入不会提升权限。
• 自动跳过这些噪音条目:.git、node_modules、__pycache__、.venv、venv、.DS_Store、Thumbs.db。
• 符号链接不跟随。

来源限制Copy Anchor Link

只接受两个来源,磁盘上其他路径一律不收:

1. 你在聊天里发给居民的附件;
2. 放进 ~/群岛/技能收件箱/ 的文件或文件夹。

这是刻意的:防止某个技能包诱导居民去读你的私密目录。

导入之后Copy Anchor Link

• 技能中心与居民档案里会标**「岛主导入」**。
• **导入的卡居民改不了。**要更新就删掉重新导入。
• 删除导入卡时,各居民工作区里的随卡副本会一并清掉。
• 重名会拦下:岛上已有同名技能时,先删旧的或换个名字。

写卡的三条建议Copy Anchor Link

1. 描述写「什么时候用」,不是「这是什么」。 名册模式下列表里只有名字和描述,描述是居民决定「要不要调它」的唯一依据。
2. 正文先写判断标准,再写步骤。 居民需要知道什么情况下该停、该问、该换方案。
3. 能写成脚本的别写成文字步骤。 随卡脚本比让模型照着长步骤执行更稳、更省积分。

完整的产品侧说明见技能卡与技能中心。