SuperAPI AI Directory

better-your-harness

General & other

View repository

Updated 10-16 08:40

About this skill

better-your-harness

Run a checkup of the AI collaboration environment on a local project, and output a self-contained visual HTML report.

Iron Rules

These three are not suggestions, they are the bottom lines that must be upheld. Violate any one of them, and this Skill loses its value.

1. Numbers may only come from the scan script; you are not allowed to make them up. Every number that appears in the report must be traceable to findings.json . Do not write quantities you are unsure of; if you cannot write it, say "not counted". Repository visibility goes through gh repo view, and you are not allowed to guess from the remote URL. Reference counterexample: a certain commercial tool reported a PRIVATE repository as public, and also got the repository owner's name wrong, which directly caused the risk rating of the highest-priority item to be distorted.

2. The value of any secret is not allowed to enter the report, the conversation, or the fix prompt. The scanner will only give you "file path + variable name + matched pattern name", and you may only write these. Do not read the contents of .env in order to "let the user confirm", and do not have the Agent print these files in the prompt. The correct reaction upon discovering a secret is to have the user add it to ignore, not to display it.

3. You may only fill in judgments for existing findings; you are not allowed to invent new findings. findings.json In findings the idarray is the candidate output produced by the script, and each entry carries a fixed analysis.json . In verdict you may only write severity / title / why / fix_prompt for these ids. If you see a problem the script did not catch, you may mention it in one sentence in

Process

1. Scan

python3 ~/.claude/skills/better-your-harness/scripts/scan.py <项目根目录> -o /tmp/harness/findings.json

A large repository takes about 15-30 seconds. The script will print the coverage of each layer and the number of candidate findings.

2. Read the JSON, write judgments

Read through all of findings.json(usually 100-300KB, focus on findings、score、security、context、usage). Then write analysis.json:

{
  "verdict": "3-5 句话的总判断。先说哪里搭得好,再说最要命的窟窿在哪,用具体数字。",
  "layers": {
    "security": { "comment": "一句话点评这一层" },
    "context":  { "comment": "..." },
    "tools":    { "comment": "..." },
    "memory":   { "comment": "..." },
    "learning": { "comment": "..." }
  },
  "findings": [
    {
      "id": "必须是 findings.json 里已有的 id",
      "severity": "high | medium | low | info",
      "title": "一句话说清是什么问题,带上关键数字",
      "why": "为什么这是问题。讲清楚它在什么情况下会真的咬人,不要空泛地说不规范。",
      "fix_prompt": "给 Claude Code / Codex 的完整口令。留空表示这条不需要修。"
    }
  ]
}

3. Render

python3 ~/.claude/skills/better-your-harness/scripts/render.py /tmp/harness/findings.json \
  -a /tmp/harness/analysis.json -o <项目>/harness-report.html

The report is a self-contained single page; double-click to view it, and you can send it directly to others.

4. Deliver

Tell the user where the report is, verbally restate the 1-2 highest-priority items, and let them read the rest themselves in the report. Do not restate the entire report in the conversation.

Rating criteria

Do not report everything as high risk; that will make the user directly ignore the entire report.

Level What situation
high Will cause data leakage, data loss, or substantive harm that is already occurring. Secret exposure only counts as high whenpublic repositoryoralready tracked by gitClearly reduces Agent effectiveness, or is a necessary precondition for high. For example, no .gitignore, Skill missing description
medium Hygiene issue; fixing it is better, but it can pass without fixing. Hanging index, missing README
low Observation, not necessarily a problem. May be the user's deliberate design
info Respect the user's deliberate design.

When you see an unusual structure, first consider whether it is intentional. For example, using codenames to name directories ( Good01 forge、02 scope) sacrificed readability, but if the entry file contains a decoding table, that is a deliberate trade-off of "obscurity for readability"; report it as info for observation, and do not treat it as a defect and deduct points. A Notion-exported archive directory is flat—that is determined by the export tool, not the user's fault.

How to write the repair instruction

The instruction is where this Skill ultimately delivers value; the report only makes people believe it should be fixed.

Must include:

  • Absolute paths; do not write "your project root directory"
  • A list specific down to file names; do not write "related files"
  • Clear verification steps (what command to run, what output to look at to determine whether it is correct)
  • A sentence saying "show me first; do not modify directly / do not commit directly"

Destructive operations must always be shown before being executed. Involving .gitignore, permission configuration,git rm --cached, and file deletion, the instruction must require the Agent taking over to first present the plan and diff and wait for confirmation. The user takes this instruction and pastes it to another Agent; that Agent does not have the context of this conversation, so the instruction itself must have built-in brakes.

Instructions involving secrets must state "do not print file contents."

What a good instruction looks like:

在 /Users/x/project 根目录创建 .gitignore,必须覆盖:node_modules/、dist/、.env、*.key

创建后执行 git status 确认这几个文件已被忽略:
  .claude/.env
  packages/api/.env.local

注意:不要打印这些文件的内容,不要把密钥值输出到对话里。
只需报告 git check-ignore 的结果。

What the scanner checked

Layer Check item
Security and hygiene Whether the root .gitignore exists and its coverage, tracked-file noise ratio, plaintext credentials (file glob + 7 types of token patterns + variable name heuristics), whether credentials are tracked or ignored, repository visibility, yolo/bypass in Agent permission configuration, number of hooks
Context quality Existence and size of entry files (CLAUDE.md/AGENTS.md, etc.), whether they contain a directory map and behavior rules, cold-start token cost, README coverage of top-level directories, maximum and average directory depth, overly flat directories, oversized text files, dangling entries in the jsonl index
Tooling Skill locations and installed count after deduplication, missing SKILL.md, missing frontmatter name/description, description too short, number of symlinks, MCP services, custom commands, sub-agents
Memory Memory directory, whether the index exists, dangling index entries, files not included in the index, line count and last write time of the structured log
Learning Iteration and retrospective directories, commits and active days in the last 90 days, Skills updated in the last 30 days, Skills untouched for more than 180 days
Zombie Skill Scan session logs to count each Skill'sactual invocation count, producing a high-frequency / never-invoked list

The criteria for zombie statistics matter a lot. Only count tool_use(name="Skill") in input.skill; do not count appearing in the Skill list in the system prompt. These two can differ by two orders of magnitude: grepping by keyword will count every Skill as used, because every conversation turn includes the list of all available Skills.

Coverage is not a score

At the top of the report, 15/33 is "items present / items expected", countable, explainable, and changes one item at a time as fixes are made.

Do not introduce a percentage-based score or maturity level into the report. That kind of number requires a baseline that does not exist, and it is not falsifiable. When users see "Task understanding 55 points," they neither know what the full score is nor how to get it to 60.

Limitations

Proactively state this clearly in the report, and don't let users think this checkup can prove what it cannot prove:

  • Describe only the repository's current state; do not assess the user's efficiency, output quality, or model choices
  • Session statistics depend on local logs; if the client is changed or the logs have been cleared, they cannot be counted
  • Credential scanning is heuristic and may miss (custom-format secrets) or falsely report (placeholders have been excluded as much as possible)
  • The "expected items" in coverage are defined by this Skill, not by industry standards

File

better-your-harness/
├── SKILL.md
└── scripts/
    ├── scan.py      确定性扫描 → findings.json(不做任何判断)
    └── render.py    findings.json + analysis.json → 单页 HTML(零依赖,图表全是手绘内联 SVG)