Guideline writing

<!-- cloud_safe: degrade -->

guideline-writing

When to use

• Creating a new guideline in docs/guidelines/{topic}/{name}.md
• Rewriting an existing guideline (not a typo fix)
• Extracting reference material out of a bloated skill or rule
• Consolidating repeated explanations from multiple skills

Do NOT use this skill when:

• The content is a constraint ("never / always") → use rule-writing
• The content is a triggered workflow → use skill-writing
• The content is a user-invoked action → use command-writing

Guideline vs rule vs skill — critical test

Intent	Artifact
"Here is knowledge skills and rules may cite"	Guideline
"Agent must always / never do X"	Rule
"When Y happens, run these steps"	Skill

A guideline is reference material. It is never a trigger. It has no description used for routing — skills and rules link to it.

Procedure

0. Run the Drafting Protocol

Creating or materially rewriting a guideline must go through Understand → Research → Draft from the artifact-drafting-protocol rule.

• Understand — which skills or rules will cite this guideline? If the answer is "none", the guideline has no home — stop.
• Research — inspect docs/guidelines/ for overlap and grep .agent-src.uncondensed/ for pages that already cover the topic. Analyze 1–2 peer guidelines in the same topic folder for tone.
• Draft — propose location (topic folder + filename) and outline. Only fill bodies once the outline is confirmed.

1. Pick the right topic folder

Folders under docs/guidelines/:

Folder	Contents
agent-infra/	Cross-cutting agent-system knowledge (naming, size, output patterns)
php/	PHP-specific reference (patterns, services, jobs, resources)
e2e/	End-to-end testing patterns

If none fits, ask the user before creating a new folder.

2. Write frontmatter

Guidelines use a minimal frontmatter — no type, no auto-trigger semantics.

---
description: "Short human-readable summary — cited by skills, not used for routing"
source: package     # or project for consumer-local guidelines
---

If you do want to polish the description for a guideline whose summary gets surfaced to agents, delegate to the description-assist skill — same approval-gated flow as for skills and rules.

3. Structure the body

• Start with a single # heading that matches the filename.
• Organize by topic, not by workflow — no numbered procedures.
• Prefer tables, bullet lists, and short code blocks over prose paragraphs.
• End with explicit "See also" links to related guidelines and the skills that cite it.

4. Wire it in

A guideline is useless if nothing cites it. Before closing the task:

• Add a link from at least one skill or rule using the pattern → See 'docs/guidelines/{topic}/{name}.md' for full X.
• Keep the citing skill/rule executable — do not hollow it out into a pointer. (Normative source: preservation-guard.)

5. Enforce the size budget

Guidelines have more room than rules but are not dumping grounds.

Category	Target
Ideal	≤ 200 lines
Acceptable	≤ 400 lines
Split signal	> 500 lines

Above the split signal, break by sub-topic into sibling files in the same folder.

6. Validate

• Run ./scripts-run src/scripts/skill_linter docs/guidelines/{topic}/{name}.md → 0 FAIL (guidelines have relaxed linting but must still parse).
• Run bash scripts/condense.sh --sync → projects updates.
• Run ./scripts-run src/scripts/check_references → no broken links.
• Run the full CI pipeline locally (see Taskfile.yml in this repo for the script list) — must exit 0 except for tolerated warnings.

Output format

1. Complete guideline at docs/guidelines/{topic}/{name}.md
2. At least one skill or rule linking to it
3. Linter + check_references.ts clean
4. bash scripts/condense.sh --sync confirmation

Gotchas

• Creating a guideline nothing cites → dead page, remove or inline.
• Pasting a workflow into a guideline → that is a skill, not reference.
• Duplicating content already present in another guideline or skill → extract into the guideline and link from both.
• Hollowing out a skill into "see guideline" — the skill must remain executable (see preservation-guard).

Frugality Standards

Apply the Frugality Charter to every guideline you author.

Examples in this artifact:

• Per the charter's index nature, guidelines describe practice patterns; they do not restate Iron-Laws from rules.
• Per the act-skip-narration rule, code examples lead with the pattern, not its motivation.
• Per the cheap-question check, guidelines do not prescribe stylistic forks ("table vs. paragraph") — pick one.

Pre-save self-check:

1. Does the guideline restate text from a rule body instead of linking the rule?
2. Are code examples preceded by narrative ramp-up?
3. Does the guideline introduce a new convention without citing the rule that holds the obligation?
4. Are sections labeled "Overview" / "Background" carrying only restatement?

Do NOT

• Do NOT add type: or alwaysApply: to the frontmatter
• Do NOT embed numbered procedures — those belong in skills
• Do NOT create an orphan guideline with no inbound links
• Do NOT reintroduce .agent-src.uncondensed/guidelines/ — relocated to docs/guidelines/

Cloud Behavior

On cloud surfaces (Claude.ai Web, Skills API) the package's scripts/check_references.ts, scripts/skill_linter.ts, and task runner are not reachable. The skill still applies — with prose-only validation:

• Emit the full guideline file as a copyable Markdown block. Do not attempt to write to disk.
• Self-check the frontmatter: description only, no type, no alwaysApply.
• Self-check the body: reference material, no numbered procedures, named in a topic folder.
• Tell the user to save under docs/guidelines/{topic}/{name}.md and run task sync && task lint-skills && task check-refs locally before committing.
• Do not call the linter, ref-checker, or condenseor — they only run on the user's machine.

Examples

Good guideline name + description:

Path: docs/guidelines/agent-infra/size-and-scope.md Description: "Golden size rules for rules, skills, commands, and guidelines"

Bad:

Path: guidelines/stuff (no topic folder, meaningless stem) Description: "Things to know"