agentsclimarketplace

Writing skill

Skill wanghong5233/agent-engineering-kit/cursor/.cursor/skills/writing-skill

A reusable, production-grade .cursor/ engineering package for Cursor / Claude Code / Agent IDEs. Rules, skills, commands, and deterministic safety hooks extracted from a real Agent project.

Install
npx -y skills add wanghong5233/agent-engineering-kit --skill writing-skill

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Write or refactor an Agent Skill / SKILL.md (agentskills.io spec; portable across Cursor, Claude Code, etc.). Use when user asks to 写/create/refactor/audit/优化 a skill or SKILL.md, or asks why a skill 没触发/太长. Do NOT use for Cursor Rules, CLAUDE.md, AGENTS.md, MCP server.

SKILL.md

5.9 KB, ~2.1k tokens by cl100k_base, as published. Nobody here has run it

Writing Agent Skills

一句话准则

一个 skill 只回答两件事：做什么 (what) + 什么时候用 (when)。其余一切能搬进 references/ 就别留在 SKILL.md，因为 body 每一行都是会话级复发 token 成本。

第一性原理：Progressive Disclosure

层加载时机预算装什么
L1 metadata (YAML)永远在 context~100 tokensname + description
L2 SKILL.md body触发时全量加载<5000 tokens / <500 行流程主干 + 关键约束 + 1-2 例子 + 指针
L3 references/ scripts/ assets/按需加载不限长篇参考、可复用脚本、模板

体量越过 L2 预算 = 错位（应下沉 L3）。Anthropic 原话："Once a skill loads, its content stays in context across turns, so every line is a recurring token cost."

Frontmatter 与 description

---
name: skill-name
description: <single line; 100-300 chars; what + when + trigger keywords + (optional) negative triggers>
---

硬约束（agentskills.io spec）：

  • name：1-64 字符，仅 a-z 0-9 -，不首尾 -、不连续 --，必须等于父目录名
  • description：1-1024 字符；单行 YAML（多行会让 Claude Code 等客户端识别失败）；甜区 <300

description 反直觉的写法——模型倾向 under-trigger，含蓄描述等于沉默。要适度 pushy：

维度反例正例
What"Helps with documents""Extract PDF text, fill PDF forms, merge PDFs"
When留空"Use when user mentions PDF / .pdf / 表单填充"
触发词含蓄显式列同义词、缩写、中英文
Negative无"Do NOT use for Word / Excel / Markdown"

完整对照与触发词组合策略：references/examples.md

Body 写作五条 + 体量信号灯

  1. 解释 why，不只 what：模型懂原因后会泛化；堆 ALWAYS/NEVER/MUST 是 yellow flag（Anthropic 明确警告）
  2. 祈使句：Read the input. ✅ vs You should read the input. ❌
  3. 具体例子 > 抽象描述：1 个 input→output 反例+正例胜过 5 段说明
  4. 每删一行问"它在拉动结果吗"：不能就删；body 越短，模型越聚焦
  5. 多变体场景上 L3：SKILL.md 写选择逻辑，每变体细节进 references/<variant>.md

体量信号灯（提交前自审）：

维度优良警告 → 行动
body 行数<50<150≥150 → 拆 references/
顶级 sections3-56-8≥9 → 合并或下沉
代码块1-23≥4 → 移 examples.md
单段落字数<60<100≥100 → 拆 bullets
description 字符<200<300≥300 → 关键词稀释
重 MUST 计数<3<6≥6 → 改 explanation

完整自检清单：references/checklist.md

标准目录结构与边界

skill-name/
├── SKILL.md              # body + 指针（必填）
├── references/           # 长篇参考，按需读
├── scripts/              # 可复用脚本
└── assets/               # 模板 / 数据

判断"是否拆 references/"：同内容在 ≥3 个 skill 重复，或单段 >300 行 → 拆。

与邻近机制的边界：

机制何时加载何时用
Agent Skilldescription 永驻；body 触发时全量反复出现的、有完整流程的任务
Cursor Rule / AGENTS.md / CLAUDE.md永远在 context编码风格、命名约定、不变量
MCP servertool call需要执行外部能力

误把 skill 当 Rule（永久加载） 会撑爆 context；误把 Rule 当 skill（按需触发） 会让永久约束有时丢失。

数量治理：Skill Pack 不是越多越好

每个 skill 即使不触发，description 也会进入可发现能力列表，形成 invisible context tax。高 star 仓库适合当 upstream benchmark，不适合整包常驻。

作用域建议上限规则
项目级 .cursor/skills/5-8只放项目强相关流程
个人级 ~/.cursor/skills/ / ~/.agents/skills/8-12放跨项目高频工程能力
总 active skill≤15超过就复审合并/禁用
marketplace / awesome list不常驻只作为检索与借鉴来源

新增 skill 前先问：它能否合并进已有 skill？能否改成 references/？是否只是开源 skill 的低差异复制？

创作循环与自检

创作循环（Anthropic skill-creator 派生）：

  1. 意图：模型在什么场景做什么？预期输出？触发词哪些？
  2. 草稿：<100 行 SKILL.md，focus 流程主干
  3. 2-3 真实测试 prompt：模拟真实用户用语（含口语、缩写、错别字）
  4. 复盘：偏离在哪里？description 没触发、body 缺指引、还是体量过载？
  5. 针对性修：能搬 L3 的搬走、能换 explanation 的换、不拉动结果的删
  6. 迭代直到稳定

提交前最小自检：

  • name 匹配目录名、kebab-case
  • description 单行、含 what+when+触发词、<300 字符
  • body <500 行、顶级 sections ≤8
  • 至少 1 个具体反例 / 正例
  • 重 MUST 已换为 reasoning，或确实必要
  • 大块内容已下沉 references/

完整 checklist：references/checklist.md

业界依据

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.