agentleFS
ShangBoyang0130ShangBoyang0130/dsh-rules/skills/规矩审查/SKILL.md

agents-md-audit

Skill1 starsChanged 14 days agoMITView on GitHub

审查规矩文件本身:指代一致性、可判定性、冲突、过拟合、长度。

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. exiao/meta-skills★ 4same name
    2. vr1e/claude-md-audit★ 1same name
    3. agentkitco/agentkit-dev-skills★ 0same name

    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.

The file

Files
SKILL.md

任务:审查规矩文件本身

这是对规矩文件的审查,不是执行规矩。目标是让文件更少、更准、更能执行。

一、审查对象

默认是这两个:

  • ~/.dsh/AGENTS.md —— 全局规矩,所有会话都读
  • 当前工作区的 AGENTS.md —— 工作区说明

用户点名要审 skill 文件时(~/.dsh/skills/*/SKILL.md),下面「二、检查项」那几条全部照用(见「二、检查项」; 别在这里另抄一份缩写清单 —— 同一份文件里两处清单必然再次过期),结论和 AGENTS.md 分开写: 产出里先写 skill 那段、再写 AGENTS.md 那段,各自分级;同一类问题两边都命中就各记一条, 好让用户按文件逐份拍板。

扫描范围就是上面这些路径。AGENTS.md 只对 dsh 的会话生效,别的软件自带的同名文件 跟用户无关;全盘扫描会读遍用户整个硬盘、 把 CPU 和风扇拉满(【实测】有过一次全盘找 AGENTS.md 让风扇狂转几秒)。 确实需要扩大范围时,先说明理由、征得同意再扫。上面这些路径不存在时,直接告诉用户, 由用户决定下一步。

三条硬约束:

  • 全局那份(~/.dsh/AGENTS.md)文件名写死 —— 改了会静默失效、看不出来。 工作区那份不一样:项目级候选名有 4 个(AGENTS.md、CLAUDE.md、 AGENTS.local.md、CLAUDE.local.md),改名未必失效。建议仍叫 AGENTS.md: 本技能与别处的指针都是按这个名字引它的(装了公开包的工作区,结构表里那一行也写的这个名字)
  • skill 文件:SKILL.md 这个文件名固定,改了技能会彻底消失、而且不报错; 文件夹名则完全自由(中文也行),身份来自 frontmatter 的 name。 name 必须 kebab-case(只允许小写字母/数字/连字符),所以会话里显示的永远是英文名。 提改名建议时,范围只到文件夹名。
  • 全局那份和 skill 文件都在工作区之外,写入需要一次沙箱授权,先跟用户说清

二、检查项

1. 指代一致性(最容易被忽略)

把所有包含「我」「你」「AI」的行抽出来逐行看。推荐约定:「我」= 用户, 指 AI 就写「AI」,「你」一律不用 —— 这样跨文件也不会冲突。

  • 两份文件必须用同一套约定
  • 跨文件冲突比单文件内部冲突更危险:两份是同时加载的
  • 报告真正读不通的歧义;一行里两个「我」都指用户、语义连贯的,属于正常
  • 省略主语、代词指向不明的地方也要报出来
  • 新加一条 bullet 之后,回头重读「它/该文件」这类回指会不会变歧义

2. 每条规则能不能判定

问:违反它,能指认出来吗?不能 → 建议删。 不可执行的规则不是无用,是有害:它稀释能执行的那些,整体遵从度会被拉低。

3. 每条规则救过场吗

能说出具体哪一次吗?说不出 → 打问号,可能是想当然写的。 这条你自己多半测不了(看不到历史会话)—— 直接说「这项我测不了,只有用户有信息」。

4. 冲突与优先级

两条规则撞车时谁优先,能一句话说清吗?说不清 → 合并或删。 先确认真的是冲突:「读证据」和「往回复里贴证据」是两件事,分开算。

5. 过拟合

只对某一次事故成立的规则 → 建议收窄或删除。 另外提醒用户:规则没变、模型变了,规则也会过期,所以审查要定期做。

6. 数量与长度

条款越多,上下文预算越挤、遵从度越分散。优先砍,不优先加。 一条「修改」如果让文件变长而没换来可判定性,先怀疑它值不值。

7. 禁止式写法

「不要…」「别…」这类禁令,改写成正面目标 —— 说出要做什么。 理由:禁止会把被禁的行为拉进上下文,反而让它更可得(「别想大象」)。 禁令只在无法正面表达的硬护栏上保留(例如「SKILL.md 文件名固定」)。

三、方法

  • 先看证据:用命令把指代抽取出来、数条款、找关键词,用实测而不是印象下判断
  • 编码坑(会毁掉整份报告):文件是 UTF-8,PowerShell 5.1 默认按 ANSI(936) 读。 后果不只是乱码 —— 汉字字节会把换行符当成双字节的第二字节吃掉,行数凭空变少, 少多少完全看内容,而且看不出任何异常。行号是审查报告的地基,读错编码整份报告 就废了。一律加 -Encoding UTF8。
  • 查 frontmatter 的键:只解析第一对 --- 之间,不要全文 grep —— 记录规则的 skill 正文里 必然出现它记录的键名(【实测】踩过:把 model-invoked 的 skill 误判成「仅限用户」)。
  • 断言工具行为必须先交叉验证:行号、行数、字节数、退出码这类「我实测到 X」, 用第二种独立方法再测一遍 —— 例如 read 的行号 × (Get-Content -Encoding UTF8).Count × 原始字节数按这个口径数出来的值:data.count(b"\n") + (0 if data.endswith(b"\n") else 1)。 ⚠️ 别直接把「LF 字节数」当行数:文件末尾没有换行时它恰好少 1,会报出一个假的编码问题。 三者一致才算过;不一致就先查清楚。交叉验证过的才标【实测】,其余标【推断】。

四、产出

先给发现清单(按严重程度分级)+ 每条的建议改法,等用户逐条拍板。

清单可以是空的。 找不到问题就直说「没问题」—— 凑出来的误报会让用户改坏本来对的 地方,比不报更有害。每条发现先自问一句:「这条我能指出一个具体的违反事例吗?」 指不出就降级或删掉。

五、产物与收尾

  • 测不了的检查项单独列一节「我测不了的」,原样上报 + 说明为什么(工具缺失 / 被沙箱挡住 / 需要用户亲自动手)—— 不要改写成「已知限制」
  • 先留快照:审查对象复制一份到工作区里一个固定的临时目录(工作区已有约定就沿用,没有就 自己定一个并写进报告,比如 _tmp\),记 SHA256 + 行数 + 字节数 —— 独立复核要审同一份字节,事后也证明得了审的是哪一版
  • 落盘一份报告:放哪沿用本工作区已有的审查报告位置(不确定就问用户);报告里写清 「行号只对上面那份 SHA256 有效」,两路发现逐条对照、每条给位置 / 问题 / 改法
  • 改完要同步生成产物(只在你的源还派生着别的副本时才适用 —— 比如公开包那套机制: 副本由 maintainer\build.ps1 从源派生):改完源要重建、跑一致性核对, 再把构建期那几道机检(痕迹检查、私有词探测)一起跑一遍。 没有这套机制的工作区跳这条(技能正文的真话源就是它自己)

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.