Help the user build a harness from scratch. With better-your-harness they form a pair: this one is responsible for building, that one is responsible for checkups.
The acceptance criteria are testable: run better-your-harness once directly on the generated harness, and the security layer and context layer should score full marks. If it can't, then this Skill has a problem.
Iron rules
0. Present a plan first, execute only after confirmation.
Before any disk-writing action, you must first run plan.py to produce an HTML plan report, so the user can see clearly on the page what will be created, what will be moved, and what is uncertain. Only after he copies back "My decisions" can you run apply.py --apply。Don't confirm on his behalf just because the plan looks fine.
1. Never overwrite files the user already has.
When scaffolding encounters a file with the same name, always skip it and report it. The migration script uses cp -n not mv. The user has accumulated things over several years; better to move less than to lose anything.
2. Migration only produces a plan; it does not take action.
migrate.py never moves files; it produces a readable, reviewable migrate.sh. Categorization is guessed from file names, and guessing wrong is normal; a human must review it and execute it themselves. You can help the user read that script and explain why a certain line is categorized that way, but do not run it for him.
3. Do not presuppose directories that won't be used. Empty directories are a negative asset: they make the Agent think there is something there, and they also lower the signal-to-noise ratio. Only generate what the user's profession truly needs, and add the rest when he needs them.
4. The interview must be short. Four questions are enough to get started. Ask everything before taking action, or people will give up by the seventh question. Once the skeleton is standing, fill in the rest slowly.
Process
Step one: interview (four questions, one at a time)
Like chatting, not filling out a form. The user can say "skip" or "let's just start like this" at any time.
1. What do you mainly do in your daily work?
Listen for his role and map it to a template:content-creator / pm / engineer / researcher / consultant / generalist. Don't read these English terms aloud to him; just match them in your own head. If you can't tell accurately, ask, "So what you produce is mainly articles, documents, code, or something else?"
2. What do you mainly want AI to help you do? This question determines which layers should be heavy. If he says "help me write things," the output layer and about-me are the focus; if he says "help me remember things," the memory layer should be established first; if he says "help me reduce repetitive work," the protocol layer and tool layer take priority. Write down his answer verbatim; it will later need to go into seed memory.
3. Where is your current material scattered? This is the migration entry point, and also where this Skill is more valuable than "giving you a template." Have him list directory paths. There may be several (an Obsidian vault, a downloads folder, a certain project directory). It's fine if there are none; that means it's a completely fresh start.
4. Where should this harness be placed? You need an absolute path.If the directory already exists and is not empty, you must clearly tell him "not a single existing file will be overwritten; files with the same name will be skipped," and continue only after he confirms.
Also confirm the naming style; give three options for them to choose from, don't ask an open question:
numbered-en(default):00-inbox10-about-me20-forgenumbered-zh:00 收件箱10 关于我20 创作plain-en:inboxabout-meforge
Step 2: Write profile.json
{
"name": "给这个 harness 起的名字",
"dir": "/绝对路径",
"role": "content-creator",
"naming": "numbered-en",
"why": "用户原话:他为什么要搭这个",
"purposes": ["产出内容", "沉淀方法"],
"git": true,
"hooks": true
}
If you want to change the output-layer directory, add outputs, which overrides the career template's default:
"outputs": [
{"key": "forge", "label": "创作", "desc": "成稿和草稿"},
{"key": "scope", "label": "选题", "desc": "待写清单"}
]
why Be sure to use the user's exact words, don't polish them. This sentence will be written into the seed memory; half a year later, what they come back to look at is this sentence.
Step 3: Produce the plan report
python3 ~/.claude/skills/star-your-harness/scripts/plan.py profile.json -o plan.html
Write the source directories the user mentioned into the profile's sources array; the plan will also include categorization suggestions.
Produce two outputs:plan.html is for people to read,plan.json is for apply.py to use.This step does not write any files.
The report has four sections: what will be built (directory tree + purpose of each level), things to watch out for (risks), what you need to decide (editable dropdowns), and confirm execution (copy button).
Give the report path to the user and let them open and view it themselves. Locally under file:// the clipboard may be unavailable; the report has a fallback: if copying fails, it will expand the content for them to select manually. If you want to be safer, start a local service:
cd <报告目录> && python3 -m http.server 8899
Step 4: Wait for the user's decision
After they finish adjusting the dropdowns on the page, they click "Copy My Decision" and paste it back into the conversation; it looks like this:
{"harness": "...", "decisions": {"<文件绝对路径>": "<目标目录名>|__skip__"}, "include_bulk": []}
Save as decisions.json。It can also be saved directly with markdown fences;apply.py will strip them off automatically.
If the user says "just go with your suggestions," that also counts as confirmation; in that case, don't pass -d and just run it; the script will use the default categorization from the plan.
Step 5: Dry run → execute
python3 ~/.claude/skills/star-your-harness/scripts/apply.py plan.json -d decisions.json # 预演
python3 ~/.claude/skills/star-your-harness/scripts/apply.py plan.json -d decisions.json --apply # 执行
The dry run will report "how many directories will be created, how many files will be created, how many will be skipped, how many will be moved, how many will not be moved, and why for each." Show it to the user, then add --apply。
Use copyfor moving; none of the source files will be touched. After execution, proactively tell them this and let them decide whether to clean up the original files.
Step 6: Health check and acceptance
The health check tool is right in the neighboring directory of the same repository:
python3 ../better-your-harness/scripts/scan.py <harness目录> -o findings.json
If installed as a Skill, it is ~/.claude/skills/better-your-harness/scripts/scan.py。
The security layer and context layer should be full marks. The tool layer will be very low (the new harness has not yet installed Skills and MCP), and the learning layer lacks "active for more than 10 days in the last 90 days." These two are a matter of time; tell them honestly not to worry about it.
Step 7: Explain the next steps
Say three things by priority, no more:
- Go fill in
about-me/the three files there. The quality of the harness depends almost entirely on this step; the directory itself does not create value. - Use it for a week, then go to
protocols/iterations/and write the first iteration record. Change whatever is not smooth there. - After a month, do another health check to see whether coverage has increased.
What is generated
CLAUDE.md 入口:目录地图 + 6 条行为规则 + 任务路由表
README.md
.gitignore 含凭证兜底那几行
.claude/settings.json 一个 hook:拦截 git add -A
00-inbox/ 没想好放哪的先扔这
10-about-me/ 我是谁 / 工作偏好 / 质量标准 ← 上下文层
20-<产出>/ 因职业而异 ← 产出层
30-vault/ 别人的东西:摘录、参考 ← 上下文层
40-memory/ MEMORY.md 索引 + 种子记忆 ← 记忆层
50-protocols/ workflows.jsonl + daily-log.jsonl + iterations/ ← 学习层
60-garage/ 脚本、Skill、自动化 ← 工具层
One README per directory, explaining what goes in, what does not go in, and how to name things.
Career templates
Only the output layer differs by career; the other six layers are universal. This is a deliberate design judgment:The skeleton of the harness has nothing to do with what industry you work in; only what you produce has to do with it.
| role | Output layer |
|---|---|
content-creator |
Creation / Topics / Published |
pm |
Requirements / Research / Delivered |
engineer |
Projects / Technical Notes / Delivered |
researcher |
Subjects / Literature / Outputs |
consultant |
Clients / Proposals / Deliveries |
generalist |
Project / Output |
The user's profession isn't in the table, use generalist then rely on outputs to customize. Don't force it.
A few places where it's easy to go wrong
Don't turn the interview into a requirements review. The user says "I just want a place to put my stuff," and that's enough; just use generalist to get started. Don't dig into his long-term goals and KPIs.
Don't create an empty directory first when he has existing materials. Run a migrate.py dry run first to see roughly how many categories his stuff falls into; you might find that the output-layer division needs adjusting.
Don't promise the migration script is correct. It guesses based on filenames. Make it clear this is "saving 80% of the grunt work," not "sorting it for you."
Don't confirm the plan on the user's behalf. Generate the report, give him the path, and stop there and wait for him. Even if the plan looks flawless to you, the act of confirming has to be done by him; that's the whole point of Iron Rule 0.
"Clearly categorized" doesn't mean it's judged correctly. The collapsed section in the report can also be changed; in real testing we caught this: a release record with "iteration" in the filename was judged into the protocol layer when it should have gone into delivered. Have the user expand it and take a look.
When the target directory is non-empty, be sure to explain it clearly first. This is the only step that could cause the user to lose things; although the scaffold doesn't cover it, he needs to be aware of it.
File
star-your-harness/
├── SKILL.md
└── scripts/
├── plan.py profile.json → plan.json + plan.html(方案报告,可交互判断,不写盘)
├── apply.py plan.json + decisions.json → 真正落盘(预演 / --apply 两段式)
├── scaffold.py 骨架生成的底层实现,也可单独当 CLI 用
└── migrate.py 归类规则的底层实现,也可单独出 migrate.sh