Write Agent Guidelines That Agents Actually Follow

Where this fits

You just spent a day adding a new workflow to your agent's CLAUDE.md. Two weeks later, the agent ignores it in a key run, or worse, follows the wrong part because the instruction read like background prose instead of a rule. You need a review process for the instruction layer itself—not just the content the agent produces. That is where guideline-writing fits: it gives you craft rules, force tiers, and a blind-review protocol for any file that tells an agent what to do.

Why agents benefit

• Operative rules over recital: The skill forces every sentence to pass a simple test—if deleting it would not change an executor's behavior, it does not belong in the body. Agents stop wasting context on filler.
• MUST/SHOULD/MAY force tiers: Explicit normative strength makes compliance measurable. An agent can distinguish a hard requirement from a suggestion and allocate effort accordingly.
• Built-in bloat control: Pruning heuristics keep instruction files short enough to remain relevant inside context windows and cheap to reload.
• Blind review protocol: Changes are evaluated without the author's narrative bias, so you catch ambiguous or contradictory rules before they ship.
• No deliberation-narrative ban: The skill prohibits the "I thought about X, then considered Y" style that pollutes many plan files, keeping guidance actionable.

Practical scenarios

Auditing a bloated .claude/ commands guide

Your project has accumulated 80 lines of setup context that reads like a wiki page. Use the skill's operative-rule test to strip anecdotes and convert the useful parts into MUST/SHOULD statements with verification steps.

Reviewing a new plan file before an agent executes it

A teammate wrote a detailed implementation plan. Instead of approving it after a casual read, you run the blind-review protocol on the plan file to ensure every instruction is unambiguous and the steps are properly force-tiered.

Making a minimal edit to a shared policy

A policy file needs one rule changed, but the previous edit added two extra paragraphs of rationale. The skill's minimal-edit discipline ensures the diff stays surgical, so agents do not absorb unrelated behavioral changes.

Add it to your agent workflow

Install the skill with:

npx skills add alfadur7/llm-wiki-newsroom --skill guideline-writing

Then, when you ask an agent to review an instruction file, reference the skill and the specific criterion set:

# Example: lint the meta layer of your project guides
python tools/lint.py meta

You can also call it directly in an agent prompt: "Use guideline-writing to review docs/agent-rules.md and flag any sentence that is recital rather than operative."

Compare before adopting

Evaluate guideline-writing against your existing process. Compare quality signals: does it produce deterministic checks, or only vibes? Check maintenance freshness: is the repo active and compatible with your agent runtime? Consider alternatives like custom lint scripts or a style guide; then factor in workflow fit—if you primarily write content rather than instruction files, this skill has narrower value. For most team setups with living CLAUDE.md or plan files, it fills a gap that general prompt-engineering advice does not. You can also see how it sits alongside other agent-craft skills on OpenAgentSkill.

Why it is worth tracking

At 82 stars and with deterministic detectors shipped in checks.py, this skill signals a shift from prompt folklore to engineering discipline for instruction files. Track it if you maintain agent-facing policies or runbooks, and evaluate it again when your project's instruction SoT grows large enough that a bad edit becomes expensive.