为Claude Scientific Writer写你自己的Skill：SKILL.md结构、脚本模板与注册完整教程
【免费下载链接】claude-scientific-writerA general purpose scientific writer项目地址: https://gitcode.com/gh_mirrors/cl/claude-scientific-writer
Claude Scientific Writer是一个通用科学写作 Agent（plugin.json 中描述为 "Deep research and scientific writing skills"），内置 26 个开箱即用的技能（Skills），覆盖文献综述、基金申请、海报制作等科研场景。本教程带你从零编写属于自己的 Skill：掌握 SKILL.md 的 YAML frontmatter 结构、辅助脚本模板与完整注册流程，让 Claude 自动识别并调用你的专属能力。
🧩 先搞懂：Claude Scientific Writer 的 Skill 是什么？
在 docs/SKILLS.md 中可以看到，当你和 Scientific Writer 交互时，Claude 会自动完成 4 步：
- 检测相关技能：根据请求判断该用哪个 Skill
- 加载资源：读取参考文档、脚本、模板
- 应用最佳实践：遵循每个 Skill 的规范
- 执行工具：调用脚本处理数据或文档
关键点：Claude 靠读取SKILL.md里的description字段来决定"什么时候该激活这个技能"。所以 description 写得好不好，直接决定了你的 Skill 会不会被触发。
💡 想本地私有使用？在
.claude/skills/下新建目录、放入SKILL.md后重启 CLI 即可自动加载，无需走注册流程（详见 docs/SKILLS.md 的 "Adding Local-Only Custom Skills" 一节）。
📂 技能目录结构：一个 Skill 长什么样？
每个 Skill 都是skills/下的一个独立目录。官方 docs/SKILL_AUTHORING.md 给出的标准布局如下：
skills/ └── my-skill-name/ ├── SKILL.md # 必需：frontmatter + 指令正文 ├── references/ # 可选：深度参考文档 (.md) ├── scripts/ # 可选：通过 Bash 调用的辅助脚本 └── assets/ # 可选：模板、示例、样式文件以真实存在的 scientific-critical-thinking 技能为例，它的目录只有SKILL.md+references/，把七大能力详解拆到了 references/core_capabilities.md。
设计原则：SKILL.md只写"Agent 该怎么行动"，长篇背景资料移到references/并用相对路径引用，让 Agent按需加载，不浪费上下文。
📝 SKILL.md 结构详解：frontmatter 字段逐个说
每个SKILL.md都以 YAML frontmatter 开头。看一个真实样例（skills/literature-review/SKILL.md 的前 9 行）：
--- name: literature-review description: Conduct comprehensive, systematic literature reviews using multiple academic databases (PubMed, arXiv, bioRxiv...). This skill should be used when conducting systematic literature reviews, meta-analyses... allowed-tools: Read Write Edit Bash license: MIT license metadata: version: "1.8" skill-author: K-Dense Inc. ---官方字段速查表（来自 docs/SKILL_AUTHORING.md）：
| 字段 | 是否必填 | 格式 | 注意事项 |
|---|---|---|---|
name | ✅ | 小写 + 连字符 | 必须与目录名一致 |
description | ✅ | 1-3 句话 | 写清"做什么 +何时触发"，这是 Agent 激活技能的唯一依据 |
allowed-tools | ✅ | 空格分隔字符串，如Read Write Edit Bash | ⚠️不要写成 YAML 列表[Read, Write]，这是新手最常见的错误 |
license | ✅ | 如MIT license | 技能内容的许可证 |
metadata.skill-author | ✅ | 作者署名 | 贡献给官方仓库时必填 |
compatibility | ⬜ | 自由文本 | 运行时要求，如"需要PARALLEL_API_KEY环境变量" |
🔑SEO 思维同理：你的
description就像搜索引擎的 Meta Description——Agent 只读它来决定点不点进来，务必包含具体触发短语（"Use when..."、"This skill should be used when..."）。
✍️ 正文写作：让 Agent 乖乖照做
frontmatter 下面是给 Agent 的指令正文。官方指南建议包含 5 个部分（可参考 skills/literature-review/SKILL.md 与 skills/scientific-critical-thinking/SKILL.md 的写法）：
- Overview（概述）：一段话说清技能目的
- When to Use（何时使用）：用列表列出触发场景
- 具体工作流：编号步骤，涉及
scripts/的脚本要给出可直接运行的完整命令 - 使用示例：示例用户提问 + 预期行为
- 环境要求：显式声明依赖（如"需要
OPENROUTER_API_KEY"），并说明缺失时的降级方案
正文中引用辅助文件一律用相对路径，例如 literature-review 正文 这样写：
A literature review runs in seven phases, documented in full with commands and templates in references/core_workflow.md🐍 脚本模板：给 Skill 配一个辅助脚本
scripts/目录放 Python 脚本供 Agent 通过 Bash 调用。以 skills/citation-management/scripts/ 为例，一个典型技能的脚本组包括：
search_pubmed.py— 检索数据库doi_to_bibtex.py— 数据转换validate_citations.py— 校验输出_common.py— 公共工具函数
写脚本时的最佳实践：
- CLI 化：支持命令行参数（argparse），因为 Agent 是通过
python scripts/xxx.py "参数"调用的 - 自带
__main__入口：正文里给出的每条命令都要能跑通 - 输出结构化：JSON 或表格，方便 Agent 解析
- 依赖声明：额外依赖写进 frontmatter 的
compatibility字段
技能正文中给出调用示例（skills/scientific-critical-thinking/SKILL.md 的真实写法）：
python skills/scientific-schematics/scripts/generate_schematic.py \ "GRADE evidence assessment flowchart" -o figures/grade.png📋 注册流程：让你的 Skill 生效
注册分两种场景：
场景一：本地私有技能（最快路径）
- 在项目的
.claude/skills/下新建目录（目录名 =name） - 放入
SKILL.md，按需添加references/、scripts/、assets/ - 重启 CLI，技能自动加载
只要目录名不与内置 26 个技能冲突，你的私有技能在内置技能刷新时也会被保留。
场景二：贡献到官方插件（完整注册）
官方技能由K-Dense-AI/scientific-agent-skills上游仓库统一管理，本仓库通过 skills.lock.json 锁定版本（当前为v2.69.0），再由 scripts/sync_skills.py 生成三处快照。完整工作流：
- 在上游仓库创建
skills/my-skill-name/ - 合入并发布上游变更
- 在 skills.lock.json 中登记技能条目（含
source/destination/sha256） - 在
.claude-plugin/marketplace.json的skills数组中注册生成路径，如：
"skills": [ "./skills/citation-management", "./skills/my-skill-name" ]⚠️ 忘记在第 4 步注册的后果：技能被选中了，但插件用户完全看不到它。
- 运行同步脚本刷新快照：
python3 scripts/sync_skills.py --update-ref <tag-or-commit>- 校验哈希与镜像一致：
python3 scripts/sync_skills.py --check- 本地测试：重装插件后提问 "What skills are available?" 确认技能出现（测试市场搭建方法见 docs/DEVELOPMENT.md 的 "Testing Plugin Locally"）
🚫三条目录是生成的，永远不要手改：
skills/、.claude/skills/、scientific_writer/.claude/skills/。
✅ 发布前质量自检清单
官方 docs/SKILL_AUTHORING.md 列出的"最低质量线"，提交前逐条过一遍：
- 触发准确：
description足够具体，只在目标请求时激活 - 自包含：脚本用项目已声明依赖可运行，额外要求已写入
compatibility - 示例可复现：
SKILL.md中每条命令都在干净环境跑通过 - 无敏感信息：不含 API key、用户名、本机绝对路径
- 语气一致：以"对 Agent 的指令"口吻写作
- 快照同步：
python3 scripts/sync_skills.py --check通过
🚀 常见问题与技巧
Q1：Skill 总是不被触发？检查description是否包含用户可能的原话表述。Agent 只读 frontmatter 做决策——把"Use when the user asks for X, Y, or Z"写进去最有效。
Q2：allowed-tools报解析错误？九成是把空格分隔字符串写成了列表。正确写法：allowed-tools: Read Write Edit Bash。
Q3：插件安装后技能列表里没有我的技能？对照 docs/DEVELOPMENT.md 的 Troubleshooting：确认 frontmatter 合法、目录已在.claude-plugin/marketplace.json中登记、marketplace.json语法和相对路径正确。
小技巧：参考仓库里写得最"克制"的技能（如 scientific-critical-thinking/SKILL.md，正文仅 197 行）作为风格模板，再对照 research-grants 这类重参考资料的技能学习references/的分层组织方式。
写在最后
写好 Skill 的秘诀就一句话：像写给搜索引擎的页面一样写 description，像写给新同事的 SOP 一样写正文。按本文的结构模板、脚本规范和注册流程走一遍，你的专属技能就能和内置的 26 个技能一样，被 Claude Scientific Writer 自动发现、加载并执行。更多细节请查阅 docs/SKILL_AUTHORING.md、docs/SKILLS.md 与 docs/DEVELOPMENT.md。
【免费下载链接】claude-scientific-writerA general purpose scientific writer项目地址: https://gitcode.com/gh_mirrors/cl/claude-scientific-writer
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 全面解析：边界规则、底层实现与工程踩坑指南)
