跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

guideline-writing

Guideline-authoring craft for instruction SoTs (.claude/ guides, CLAUDE.md, plan files) — operative rules vs recital, MUST/SHOULD/MAY force tiers, pruning, bloat control, blind review protocol, deliberation-narrative ban. Use when writing, editing, or reviewing an agent instruction file, policy, runbook, command SoT, or plan file, or when a guideline change needs a minimal-edit or blind review.

alfadur7 · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

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

技能说明


name: guideline-writing description: Guideline-authoring craft for instruction SoTs (.claude/ guides, CLAUDE.md, plan files) — operative rules vs recital, MUST/SHOULD/MAY force tiers, pruning, bloat control, blind review protocol, deliberation-narrative ban. Use when writing, editing, or reviewing an agent instruction file, policy, runbook, command SoT, or plan file, or when a guideline change needs a minimal-edit or blind review.

Guideline Writing

Craft for authoring the instruction layer itself — the .claude/ guide SoTs, CLAUDE.md, and plan files. Content pages have the four content-craft skills (jrn·con·enc·cit); this skill is their counterpart for the meta layer. Dotted IDs: gdl.* (criteria.json); the deterministic detectors live in checks.py and run inside python tools/lint.py meta.

Operative Rule vs Recital

Every sentence in a guideline is one of two kinds, and only the first belongs in the body:

  • Operative rule — tells the reader what to do, when, and how to tell they did it right. Test: delete the sentence; if an executor could now act differently and still believe they complied, the sentence was operative.
  • Recital — explains how the rule came to be: options weighed, benchmarks absorbed, incidents survived, dates adopted. Recitals are history; history's SoT is log.md (append-only). A recital in the body is deliberation narrative — the central antipattern this skill exists to prevent.

A failure mode earns at most one line in the body — the concrete trigger the rule guards against, stated as a present-tense condition ("a partial edit bumps only the date and masks body staleness"), never as a war story ("after the 05-20 incident we decided…"). The story goes to log.md.

Force Tiers — MUST / SHOULD / MAY

State every rule at exactly one force tier, and make the tier visible in the wording:

TierWordingReader's obligationVerification
MUST"is mandatory" · "never" · imperativeno discretion; violating it is a defectlint-gate or blocking hook where possible
SHOULD"by default" · "prefer" · "unless"may deviate with a stated reasonadvisory hook · review lens
MAY"can" · "optionally"pure permissionnone

Antipattern: hedged MUSTs ("should generally always…") and decorated MAYs ("it is strongly recommended to consider…"). If you cannot pick the tier, you have not finished deciding the rule — finish deciding before writing.

Pruning

A guideline corpus only stays executable if rules leave at the same rate reality invalidates them:

  • Prune-or-enforce: a rule that is neither checked (lint·hook·review lens) nor followed is dead weight — either wire an enforcement surface or delete it. Keeping it "as documentation" is the recital antipattern wearing a rule's clothes.
  • Deprecation signal: a detector or lens with 0 surfacings across 5 consecutive batches is a deletion candidate (mirrors the desk promotion loop's burn criteria).
  • Delete whole units: prune at the bullet/section level, not by shaving words — a half-pruned rule reads as a weaker rule, not a shorter one.

Bloat Control

Absorb into an existing section, table, or matrix by default; create something new only after proving no matching pattern exists.

5-step self-check (mandatory just before finishing a guideline or plan edit):

  1. New section/table/matrix vs a one-line absorption into an existing section — absorb by default
  2. Zero copies of another SoT's table/matrix — replace with a cross-reference
  3. Zero new Risk/invariant/caveat sections by default — prefer attaching a qualifier to an existing section
  4. When the changed lines ≥ 50, a mandatory minimum-edit re-review
  5. Read the full context of each changed file before declaring the edit done

4 red flags (a single hit forces the 5-step re-review):

  • ≥ 2 new sections added
  • ≥ 50 changed lines
  • a new table or matrix added
  • the same information already exists in another SoT

File naming (T1 prescriptive default): a new memory/policy/hook file takes an imperative form — no_X · X_to_Y · X_not_Y. Descriptive names (*_voice · *_posture) require two-step inference on recall and match utterance patterns weakly.

Blind Review Protocol

A guideline edit is reviewed by a reader who did not write it and does not know the deliberation behind it. In this project it runs as rung 3 of the Guideline Verification Ladder (.claude/agents/editor-in-chief.md); the protocol itself is project-agnostic:

  1. Input carries no author intent — the diff, but no chat context and no rationale memo. The reviewer sees exactly what a future executor will see. Blindness withholds the author's intent, not file access: the reviewer reads each touched file whole (post-edit) before judging, since a hunk judged in isolation invites mechanical fixes that seed the next round's defects. On a re-pass the previous round's findings come too — that is reviewer output, not author intent.
  2. Classification reply is mandatory: the reviewer returns, per hunk, a two-way verdict — substantive (an executor would act differently after this change) or invariant (wording/structure only, behavior unchanged) — plus any defects found against this skill's criteria.
  3. Defect form: criterion id (gdl.*) · location · one-sentence issue · one-sentence fix direction · severity (critical / high / medium / low — the caller's fix-now-or-defer policy keys off it). A direction is not drafted replacement text: a reviewer asked to author the remedy tends to inflate its own findings to justify it. Abstract criticism ("feels verbose") is not a defect.
  4. Self-containment probe: the reviewer must be able to state what the rule obliges without opening another document; if they cannot, flag gdl.self-contained.

Worked Examples

  1. Recital → operative — ✗ "After comparing per-event shell hooks with a unified dispatch
阅读完整来源 ↗