agentleFS
ShangBoyang0130ShangBoyang0130/dsh-rules/skills/给AI写文档/SKILL.md

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

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.
  • AWSSkill

    to-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

  • liufeng1976Skill

    setup-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

  • AWSSkill

    wizard

    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

  • J03Fr0stSkill

    writing-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

  • openchamberSkill

    clack-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

  • MicrosoftSkill

    cloud-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

The file

Files
SKILL.md

给 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 文件名固定」), 而且最好配一句正面目标。

七、交稿之前:三项自检(完成标准)

改完任何一份这类文档,逐项做完再交:

  1. 重读指代 —— 「我」= 用户,指 AI 就写「AI」,全文不出现「你」;引用了别的 skill / 文件的专名或路径,逐个对磁盘核一遍(名字会被改、路径会搬)。 新加或改写一句之后,回头重读「它 / 该文件 / 该 skill」这类回指有没有变歧义。
  2. 逐条过 no-op —— 每条相对默认行为改变了什么?
  3. 报长度变化 —— 这一版比上一版长/短了多少(给实测数字,不给预估)。

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.