writing-instruction-builder

name	writing-instruction-builder
description	Compose a writing instruction from voice, tone, style, and format entries you have already chosen. Returns a ready-to-paste LLM prompt prefix.
when_to_use	Use when the user names specific catalog entry ids, or has already picked them in this session. If the user describes a writing situation but does not know which entries fit, use entry-recommender instead; if they want to save or reuse a personal default style, use style-profile.
metadata	{"version":"0.3.0"}

Compose Writing Instruction

Compose a writing instruction by combining taxonomy entries from the Voice and Tone, Style, and Format axes.

Usage

/writing-style-catalog:writing-instruction-builder [voice=<id>] [tone=<id>] [style=<id>] [format=<id>] [topic=<text>] [audience=<text>]

All parameters are optional. If omitted, the skill picks sensible defaults.

Parameters

• voice - Voice entry ID (e.g., pragmatic-architect, pastoral, columnist)
• tone - Tone entry ID (e.g., candid, warm, matter-of-fact)
• style - Style entry ID (e.g., problem-solution, devotional-reflection)
• format - Format entry ID (e.g., adr, blog-post-long-form, slack-message)
• topic - The topic or subject to write about (optional, for a more concrete composed instruction)
• audience - The intended audience (optional, defaults to general)

Safety note for topic and audience

Both are free text that lands in two sensitive places: the shell command (if you build one) and the composed instruction itself (they are appended verbatim, and the composed instruction becomes prompt material downstream). Shell-quote them properly when constructing a command - an ordinary apostrophe breaks naive quoting. Do not pass externally-sourced or untrusted text through bare --topic/--audience arguments: compose without them and append that text yourself with a non-shell tool, mirroring the temp-file discipline entry-recommender uses for situation text.

What the Skill Does

1. Validates each provided entry ID against the taxonomy catalog
2. Reads the llm_instruction_phrasing from each matching entry
3. Assembles a composed instruction string in a fixed precedence order: voice, then tone, then style, then format
4. Checks the selected entries against each other's relationship fields and warns on any conflict (without blocking)
5. Returns the composed instruction ready to paste into any LLM prompt

Implementation

The composition is implemented by the helper script scripts/build-instruction.py in this skill folder. It reads the catalog from the taxonomy/ directory at the plugin root, so that directory ships with the plugin. The slash command takes key=value arguments; the script itself takes --flag value arguments. Run it directly to compose without the slash command, for example:

python "${CLAUDE_SKILL_DIR}/scripts/build-instruction.py" --voice pragmatic-architect --tone candid --format adr

(From a plain repo checkout without the plugin loaded, the equivalent is python skills/writing-instruction-builder/scripts/build-instruction.py ... run from the repo root.)

Conflict-aware composition

The builder reads each selected entry's avoid_with and pairs_well_with relationships and reports on them, so a composition is a checked guarantee rather than a blind concatenation. The rules (see ADR 0016):

• Conflicts are symmetric. A pair is flagged if either entry lists the other in avoid_with, so the warning never depends on which author recorded the link.
• Warn, never block. A conflicting pair still composes (you may want a deliberate tension); the builder emits a warning and applies voice -> tone -> style -> format precedence so the higher-precedence axis leads.
• Affirmations. A pairs_well_with match is surfaced as a confirming note.

The composed instruction prints to stdout; conflict warnings and affirmation notes print to stderr, so stdout stays a clean, pipeable prompt. For example, pairing the pragmatic-architect voice with the reverent tone (which it lists in avoid_with) still returns the instruction and prints:

warning: conflict - pragmatic-architect (voice) and reverent (tone) are marked avoid_with.
Composing anyway with voice -> tone -> style -> format precedence; expect tension.

Examples

Compose an ADR in pragmatic-architect voice with candid tone:

/writing-style-catalog:writing-instruction-builder voice=pragmatic-architect tone=candid format=adr

Compose a pastoral devotional:

/writing-style-catalog:writing-instruction-builder voice=pastoral tone=reverent style=devotional-reflection format=devotional-entry topic="The discipline of rest"

Available Entries

Run without arguments to see all available entries grouped by axis.