better-skill
A doctor skill for agent skills that picks an architecture, audits against 21 red lines and returns a report with line references
- 237 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- In the fix mode the agent patches the files of other skills, so a report and a backup should come first
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/better-skillDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- In the fix mode the agent patches the files of other skills, so a report and a backup should come first
This is third-party code. Review the repository files before installing.
What it does
better-skill is a skill for working on other skills. It does four things: pick an architecture before the work starts, audit a finished skill, write targeted fixes and compare several skills with each other. The agent first reads every file of the skill under review and only then draws conclusions. The audit runs over four layers: file structure, description, the body of SKILL.md and trigger conditions. Each finding gets a P0, P1 or P2 priority and a line reference. A separate list of 21 red lines marks things that must not be done. Fixes are allowed only after the report, as `str_replace`-level patches rather than a full rewrite of the file. For comparison the skill has five metrics: the share of cases where a skill works without user edits, trigger rate, number of round trips, token footprint and autonomy level. The creation mode walks a skill from choosing one of seven architecture paradigms to comparing runs with and without it. The main text and description are in Chinese; the README has an English edition.
Who it is for. Authors and maintainers of skills for Claude Code and Codex who have dozens of SKILL.md files and no common yardstick for their quality.
Good fit when
- A skill fires at the wrong moments and you want to find out why from its description and the checklist
- Before creating a new skill you want to choose one of seven architectures instead of writing at random
- You need a report on a set of skills with P0, P1, P2 priorities and line numbers for fixes
- Two skills do similar things and you need a decision to keep, merge or retire one
- A skill is ready and you want to compare runs with and without it to confirm the benefit
Not a fit when
- You need to package a skill, distribute it across machines or register it: the skill explicitly declines those tasks
- You want Anthropic's official skill evaluation toolbox with ready scripts: `skill-creator` is better for measurements
- The skill under review is not a SKILL.md but a different instruction format
- You want a fully automatic run without questions: for three or more skills the agent first asks you to confirm the scope
Example request
Use better-skill to audit my skill in skills/release-notes and show findings with priorities and line numbersLimitations
- The skill and its description are written in Chinese, and so is the main README. An English README exists, a Russian one does not.
- Marks such as a trigger rate of at least 90% and ZSAR of at least 85% come from an audit of the official skill library and are not calibrated for your environment.
- Two roles in the table, `skill-ingest` and `skill-stocktake`, are described as the author's internal skills and are not in the repository yet.
- The 96 versus 85 score against `skill-creator` is the author's own structured count, not an independent test.
How to disable. Delete the `better-skill` directory from the agent's skills folder and start a new session. The skill makes no other changes until you ask it to write fixes.
FAQ
How do I install better-skill in Claude Code?
Clone the repository into the skills directory: `git clone https://github.com/YTruman/better-skill.git .claude/skills/better-skill`. Then open a new session and say: "Use better-skill to audit my skill". The README has no dedicated install command yet and lists it as upcoming.
Which modes does better-skill have?
Four: creating a new skill, auditing a finished one, applying fixes from the report and comparing several skills. If the request is unclear, audit runs by default as the safest mode.
Does better-skill change my files on its own?
Only in the fix mode and only after a report. It makes small patches that name the report finding each one answers, and it re-checks the affected items after the change.
How is better-skill different from skill-creator?
The author treats them as complementary: the official skill-creator makes sure a skill can be built, while better-skill judges its quality and longevity. For measurements better-skill uses the evaluation loop from skill-creator.
Does it work if my skills are written in Russian?
The project has no Russian examples. The trigger optimization method is described as working for Chinese and English descriptions, so test the quality of the review on one Russian skill first.
Discussion
No questions or reviews yet.
Related
SkillsA skill that designs, tests, evaluates and packages other agent skills, starting from architecture
A workshop skill: the agent vets a finished skill, finds peers, scores it and edits step by step, testing every change.
A skill for creating skills that proves them by behavior: before-and-after runs, regression evals and ecosystem audit
A meta-skill that takes a vague idea to a finished agent skill: it designs, writes the files, checks them and refines by evidence
Darwin Skill
darwin-skill
A skill that improves other skills: scores SKILL.md on nine criteria, edits, tests with prompts and reverts
A skill that trims other skills: it cuts the excess, fixes outdated commands and checks that agents do at least as well
README in short
The page explains why skills need an audit, shows four working modes and installation via `git clone`. Then come the evidence: an audit of 332 official skills, a 96 versus 85 score, a caveat about its precision and the Better family roadmap.
README badge
Original SKILL.md
--- name: better-skill description: Skill 工艺定版标准（Better 家族·技能医生）。萃取自业内最成熟可靠的 Skill 体系——官方 300+ 技能全量审计与 skill-creator/doc-coauthoring/canvas-design/mcp-builder/webapp-testing 等旗舰案例深度拆解，经五轮对抗打磨与三源交叉测评定版（本标准 S 级；官方 skill-creator 85 分 vs 本体系 96 分对撞）。当要创建新 Skill 前做架构选型、给现有 Skill 做体检巡查短板、审计 Skill 质量、升级优化纠偏某个 Skill、或对比评估多个 Skill 高下时使用。含七范式选型、四层 P0/P1/P2 检查表、21 条执行红线、ZSAR/触发率量化标尺、Anti-Slop 反塑料词库、全套文档模板与评测闭环。造前咨询→施工→评测→触发优化→体检→处方→会诊全管线（技能创建默认入口），具工程化落地能力。 --- # Better Skill · Skill 工艺定版标准（技能医生） ## 0. 身份与出身 - 我是 Skill 的**医生兼总建造师**。核心动词是**诊**：先诊断，后开方；没有体检报告，禁止动刀。 - 管五件事：**造前选型咨询、从零施工创建（本技能=技能创建默认入口）、造后体检巡查、靶向处方升级、横向会诊评估**。 - 出身（凭什么信这套标准）：本标准基于官方 300+ 技能库全量审计与旗舰案例拆解萃取，融合官方教程（权威地基）与中文头部技能工厂的组织方法论（推行治理），经五轮高强度对抗式打磨定版；三源交叉测评中获评 S 级（工业级标杆），与官方 skill-creator 对撞测评 96 vs 85。证据链全文见 `references/provenance.md`。 ## 1. 接诊路由（四种模式） | 模式 | 触发场景（用户会这么说） | 动作 | 必读资源 | |---|---|---|---| | **A 创建** | "我想做个新 Skill""把这套流程固化成 Skill" | 选型 → 自由度定级 → 目录蓝图 → 施工写包 → 评测闭环 → 描述触发优化（全管线） | `paradigms.md` + `templates.md` + `eval-loop.md` | | **B 体检** | "看看这个 Skill 有什么短板""巡查/审计一下质量" | 四层 P0/P1/P2 扫描 + 21 条红线扫描 → 出体检报告 | `checklist.md`（评级再读 `metrics.md`） | | **C 处方** | "升级/优化/纠偏这个 Skill" | 先有体检报告（本次会话产出，缺则先做 B）→ 靶向补丁 | `checklist.md` + `templates.md` | | **D 会诊** | "这两个 Skill 哪个好""要不要合并" | 统一标尺横评 → 对比表 + 保留/合并/退役建议 | `metrics.md` | A 创建，用大白话说：先选技能的结构（读 `paradigms.md`）→ 定哪些步骤要严格、哪些放开（自由度定级）→ 画出文件清单（目录蓝图）→ 写技能文件（读 `templates.md`）→ 拿真实题目对比"用技能 vs 不用技能"的效果（读 `eval-loop.md`）→ 调整简介，让 AI 该用时想得起来（描述触发优化）。需要讲清"为什么这样设计"时，再读 `principles.md`。 B 体检，用大白话说：先读完要检查的技能文件，不凭印象下结论（读 `checklist.md`）→ 从四个方面逐项检查：文件结构、技能简介、正文内容、什么时候会被调用（四层扫描）→ 再对照 21 条红线，看有没有犯“绝对不能做”的错 → 写体检报告，每个问题都标出在哪一行、有多严重（P0 致命 / P1 重要 / P2 可优化），没问题的地方明确写“通过”。需要打分评级时，再读 `metrics.md`；动笔写报告前，可以先看 `examples/perfect-audit-report.md` 的样板。一次要查 3 个及以上技能时，先列清单，等用户确认范围再开工。 C 处方，用大白话说：先确认本次对话里已经有体检报告；没有就先做 B，不凭印象直接改 → 只修报告里列出的问题，每条修改都要说清对应报告的哪一条（读 `checklist.md`）→ 按补丁格式一次只改一小处，不整篇重写，也不顺手改无关内容（读 `templates.md`）→ 改完自动复查受影响的条目，给出修改前后的对比。 D 会诊，用大白话说：用同一把尺子比较两个或多个技能（读 `metrics.md`），从五个方面打分：用户不改就能直接用的比例（ZSAR）、该用时能不能被叫出来（触发率）、完成任务要来回几次、Token 占用量（占用多少文字量）、能自己做到什么程度（自治等级）→ 输出对比表和一句话结论 → 给出“保留 / 合并 / 退役”的建议。只给建议，真正的合并或删除交给其他技能执行。 路由规则： - 意图模糊 → 默认 B（体检是最安全的默认动作）。 - **B 模式批量确认门**：体检对象 ≥3 个或含"全库/巡检"时，先列对象清单与预计工作量，请用户确认范围后再开工；单对象直接执行。 - C 模式强制前置体检报告；禁止凭印象直接改文件。 - 处方完成后自动触发复诊：复扫受影响条目，报告前后对比。 ## 2. 医生宪法（红线，违反即事故） 1. **先诊后治**：任何修改建议必须能指回体检报告的具体条目（如"必修 P0-3 缺初始对话协议"）。 2. **外科手术式修改**：只开 `str_replace` 级靶向补丁；严禁全量重印目标 SKILL.md（初始创建除外）。