HumanLayer Skills: instruction preservation and reviewable control loops
Try HumanLayer instruction cleanup with a protected-command worksheet
Evaluate a proposed CLAUDE.md rewrite using synthetic input, preserved commands and explicit safety constraints before changing future agent guidance.
What you will learn
- Create a source whose meaning you can check
- Review deletion as carefully as formatting
- Evaluate behavioral benefit separately
Before you start
- Repository instructions and basic GitHub Actions concepts
- Understanding of review scope and persistent agent context
Design a bounded, inspectable workflow and distinguish template assumptions from tested behavior.
Key takeaways
- Protect commands and consequential constraints before rewriting.
- Do not assume a documented rule is enforced by a linter.
- Structural preservation and behavioral adherence are different tests.
Create a source whose meaning you can check
Start with a synthetic repository guide containing project identity, a small directory map, build and test commands, and one domain-specific rule. Add a protected constraint such as requiring review before publishing. Keep a copy of the original and request a proposed rewrite only, not a direct edit to an active repository.
The improve-claude-md skill keeps foundational context plain, groups commands together and wraps targeted guidance in conditional important blocks. It also asks to retain every original command. Those are inspectable output properties even before evaluating whether a model follows the resulting guide more reliably.
Review deletion as carefully as formatting
The skill recommends removing linter-enforceable guidance, stale code snippets and vague instructions. Apply judgment: do not remove a safety or release constraint simply because it resembles a process rule. Confirm that the supposed linter check actually exists and is enforced before treating its documentation as redundant.
Compare the rewrite with the source using a table of preserved commands, protected constraints, moved rules and removed text. A shorter file can still be worse if it drops a rare but important migration command. Retaining a command in the guide does not authorize executing that command during the rewrite exercise.
Evaluate behavioral benefit separately
After a human accepts the proposed structure, a later controlled model trial can compare representative tasks using original and revised guidance. Keep model, task and acceptance conditions fixed, and record missed instructions. Valid-looking XML-style blocks are not proof that the host gives them special execution semantics.
We did not edit this workspace’s CLAUDE.md or AGENTS.md and did not run the proposed model trial. The exercise helps readers inspect preservation and scope first. Any claim about better adherence must come from measured behavior, not from the visual neatness of the rewritten document.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Prepare synthetic instructions and a protected-item list.
- 2
Request a proposed rewrite without applying it.
- 3
Compare commands, constraints and deletions.
- 4
Measure adherence only in a separate controlled trial.
Copy-ready example
{
"exercise": true,
"originalCommands": [
"npm run build",
"npm test",
"npm run migrate:review"
],
"protectedRules": [
"Review before publishing"
],
"executeCommands": false,
"applyRewrite": false
}Frequently asked questions
Should cleanup execute the commands it preserves?
No. Listing commands is documentation, not permission to run them.
Do important blocks guarantee instruction following?
No such guarantee was established by this review.
Sources
- HumanLayer Skills / plugins/improve-claude-md/skills/improve-claude-md/SKILL.mdSource checked 2026-09-14