writing-for-agents
Skill1 starsChanged 14 days agoMITView on GitHub
新建或修改 skill、AGENTS.md,或往任何会被 agent 读到的文档里写字之前,先读这个 —— 含 invocation 判定、description 写法、长度判据、交稿前三项自检。
193 other projects use a version of this.
Adopted by
Most recently taken up by
- bamlab/flashlighttheir own version, first seen Nov 16, 2026
- moisesrj97/skillstheir own version, first seen Nov 16, 2026
- ian-pascoe/skillstheir own version, first seen Nov 16, 2026
- endalk200/skillstheir own version, first seen Nov 16, 2026
- tunnckoCore/skillstheir own version, first seen Nov 16, 2026
- gfunc/skillstheir own version, first seen Nov 16, 2026
Used with
Projects with it also use to-questionnaire, setup-ts-deep-modules and 9 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
AWSSkillto-questionnaire
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
Also in 95 projects that use this
liufeng1976Skillsetup-ts-deep-modules
Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.
Also in 40 projects that use this
AWSSkillwizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
Also in 126 projects that use this
J03Fr0stSkillwriting-for-humans
Write and revise human-facing prose so it is clear, specific, natural, and faithful to the author's intent and genre. Use for emails, chat messages, articles, reports, documentation, announcements, talks, and other prose when the user asks to draft, diagnose, edit, rewrite, make writing less formulaic or less AI-like, sound more natural or direct, or match a supplied voice. Do not use for agent instructions such as skills or AGENTS.md, code-only work, verbatim transcription, or translation without editorial changes.
Also in 7 projects that use this
openchamberSkillclack-cli-patterns
Use when creating or modifying OpenChamber CLI commands, prompts, terminal output, non-TTY behavior, `--quiet`, or `--json` behavior.
Also in 3 projects that use this
MicrosoftSkillcloud-architecture-diagram
Create, edit, or review Azure and Microsoft ecosystem architecture, GitHub CI/CD, and auth/API diagrams as editable draw.io files; resolve Microsoft and GitHub icons. Use for architecture visualization, diagram critique, or missing icons. Azure DevOps only when explicitly requested. Not for competing-cloud architecture, deployment, live discovery, security certification, or unrelated charts.
Also in 3 projects that use this
Other versions193 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 193
- mattpocock/skills★ 325ksame name
- The-Vibe-Company/quivr★ 40ksame name
- QuivrHQ/quivr★ 40ksame name
- formbricks/formbricks★ 13ksame name
- btriapitsyn/openchamber★ 13ksame name
- openchamber/openchamber★ 13ksame name
- ArcReel/ArcReel★ 6.6ksame name
- vinvcn/mattpocock-skills-zh-CN★ 5.8ksame name
- withcoral/coral★ 5ksame name
- bestofjs/bestofjs★ 3.1ksame name
183 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- handoffSkill
- content-preflightSkill
- exploration-outsourcingSkill
- grill-meSkill
- agents-md-auditSkill
- wait-whatSkill
The file
Files
给 agent 写文档
目标一句话:让文档每轮花得少、触发得准、不会烂掉。
(本 skill 自己是 model-invoked 的样板:写文档时 agent 必须自己想到来调它,所以它值得付一行常驻 description。)
一、先定 invocation —— 它决定后面一切
判定只有一句:只有 agent 必须自己够到它、或 别的 skill 必须够到它 时,才做成 model-invoked。只在手动触发时才用 → 做成 user-invoked。
| model-invoked(默认) | user-invoked | |
| 怎么设 | 省略 disable-model-invocation | 加 disable-model-invocation: true |
| description 面向 | 模型:保留触发分支 | 用户:一句话摘要,去掉触发列表 |
whenToUse | 写(模型字段) | 不写(此时它什么都不做) |
| 每轮上下文成本 | 1 行(description 常驻) | 0 |
| 谁能触发 | 模型 + 用户 | 只有用户,走 / 菜单 |
| 别的 skill 能调用吗 | 能 | 永远不能 |
【实测】加上 disable-model-invocation: true 之后,skill 当场从模型目录消失,但仍留在 /
菜单里(带「仅限用户」标记)—— 这条是在 dsh 上实测的;/ 菜单本身就是 router —— user-invoked skill 再多,也不需要
另做一个 router skill。
二、description 就是「指针」
指针 = 上下文里的一条引用,它命名某份不在上下文里的材料,并编码了什么条件下该去取它。
- 措辞决定触发,不是目标决定触发。 措辞弱的指针 = 方差 bug:先磨措辞,磨不动才把内容内联
- 一个分支一条;同义词是同一个分支写了两遍 —— 合并
- 常驻的每个字都在每轮花钱 → 指针比正文更该狠砍
- 开头那几个字在干触发活,把最强的词放最前面
- 指针里重复正文已有的内容 = 白花负载
三、硬约束(dsh 实测,照抄即可)
| 项 | 规则 |
| 文件名 | 必须叫 SKILL.md。改了 skill 会彻底消失,而且不报错 |
| 文件夹名 | 自由,中文也行 —— 身份来自 frontmatter 的 name,不是文件夹 |
name | 必须 kebab-case(小写字母/数字/连字符),否则整个 skill 被跳过 |
| 可用的键 | 只有 name、description、whenToUse、disable-model-invocation、user-invocable、metadata。别的工具家的键(如 argument-hint)写了不生效(判据:模型目录里看得见 = 生效;不生效时既不报错、也不占上下文) |
| 放哪 | ~/.dsh/skills/<随便什么文件夹名>/SKILL.md —— dsh 专用的放这儿;想给别的 agent 工具共用的,放 ~/.agents/skills/(两个根都会被扫)。代价:disable-model-invocation / whenToUse / user-invocable 是 dsh 专有键,放过去不保证生效 —— 要 user-invoked 就留在 ~/.dsh/skills/ |
| 新建后多久可见 | 模型目录当场生效;/ 菜单要重启 dsh 服务才看得到(重启 = 关掉正在跑的 dsh 进程再启动;用包里的 安装.bat 装过的话,工作区里有一个 活跃\启动dsh.bat 可以直接双击。进程级收集缓存按 preset 作用域存,同 preset 的所有会话共用一条 —— 开新会话和刷新页面都没用) |
| 什么会被自动读 | AGENTS.md / CLAUDE.md 加同名 .local 覆盖层,从项目根到当前目录每层都算(典型情形:全局 ~/.dsh\AGENTS.md + 工作区 AGENTS.md + 工作区 AGENTS.local.md 共 3 份;全局那份没有 .local 变体 —— 要放私有补充就放工作区那份)。skill 正文只在被调用时才进上下文 |
四、长度:优先砍,往「披露」推
信息分三层:正文步骤 → 正文参考 → 披露出去的参考(推到旁边的文件,用指针引)。
- 分支测试:每个分支都要的写正文;只有某些分支需要的,推到指针后面
- 沉积是默认下场:加了觉得安全、删了觉得可惜,最后要钻穿才能找到还活着的那些
- 优先砍,不优先加。 一条修改让文档变长、却没换来可判定性,先怀疑它值不值
- 「优先砍」砍的是条目,不是容器。 一个文件里混着耐久内容和易变内容时,退场规则要分级: 易变的删行、耐久的留着 —— 整份删掉的话,下次得把机制知识重写一遍
- 一份纯参考的文档(全是规则、没有步骤)是正常形态,不是缺陷
五、判断该删哪条:no-op 测试
问:这条相对模型的默认行为,改变了什么? 没改变 = no-op,白花负载。整句删掉,不要只删几个词。
有分歧时:跑一遍解决,不靠辩论 —— 争的其实是各自心里的「默认」假设。
六、写法:说正面目标
用「不要…」「别…」来引导,会把被禁的行为拉进上下文,反而让它更可得(「别想大象」)。
说出要做什么。禁令只留给无法正面表达的硬护栏(例如「SKILL.md 文件名固定」),
而且最好配一句正面目标。
七、交稿之前:三项自检(完成标准)
改完任何一份这类文档,逐项做完再交:
- 重读指代 —— 「我」= 用户,指 AI 就写「AI」,全文不出现「你」;引用了别的 skill / 文件的专名或路径,逐个对磁盘核一遍(名字会被改、路径会搬)。 新加或改写一句之后,回头重读「它 / 该文件 / 该 skill」这类回指有没有变歧义。
- 逐条过 no-op —— 每条相对默认行为改变了什么?
- 报长度变化 —— 这一版比上一版长/短了多少(给实测数字,不给预估)。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

