prompt-decorators-usage - SKILL.md Agent Skill

name: prompt-decorators-usage description: Use when a user's prompt would clearly benefit from a reasoning, structure, tone, or verification decorator - or when they ask "what decorators should I use?". Teaches when and how to suggest inline `::Name(params)` sigils instead of repeating verbose prompt-engineering instructions manually. context: fork agent: general-purpose

Prompt Decorators Usage

This skill teaches when to suggest prompt decorators to the user and how to apply them - either as inline sigils, always-on config, or by switching on auto-decorate mode.

Prerequisites

The prompt-decorators plugin is installed (the user installed it from the Synapti marketplace).
The UserPromptSubmit hook is wired and active.
The decorator catalogue is available - browse with /decorate list or /decorate search <term>. Counts below reflect the catalogue at the time this skill was written; run /decorate list for the current set.

Workflow

Use TodoWrite to track these steps when invoked from another workflow:

1. Identify the decoration intent (reasoning / structure / tone / verification / minimal / meta) 2. Pick 1-3 decorators from the catalogue that match the intent 3. Decide the delivery method (inline, always-on, or auto mode) 4. Communicate the suggestion to the user with exact syntax

Step 1: Identify the decoration intent

Match the user's prompt to one of the catalogue's core categories.

All decorator names below are verified against the vendored registry at claude-code-plugin/vendor/prompt_decorators/registry/core/ at the time this skill was written. The catalogue grows and names can change; if any suggestion below doesn't appear in /decorate list, trust the CLI over this table and use /decorate search <term> or /decorate list <category> to find the current equivalent.

Category	Trigger phrases in the prompt	Real decorators (verified)
reasoning	"why", "explain", "analyze", "compare", "pros/cons", "trade-offs"	`TreeOfThought`, `FirstPrinciples`, `RedTeam`, `Socratic`, `RootCause`, `Debate`, `Contrarian`, `Abductive`, `Deductive`, `Inductive`, `BlindSpots`
structure	"list", "outline", "summarize", "table", "bullet", "organize"	`Outline`, `Summary`, `TableFormat`, `Comparison`, `Bullet`, `Layered`, `Nested`, `DecisionMatrix`, `Prioritize`, `Timeline`
tone	"concise", "brief", "detailed", "academic", "formal", "simple"	`Concise`, `Detailed`, `Academic`, `ELI5`, `Professional`, `AsExpert`, `Audience`, `Persona`, `Creative`, `Narrative`
verification	"verify", "fact-check", "cite", "sources", "evidence", "risks"	`CiteSources`, `FactCheck`, `Confidence`, `Uncertainty`, `Limitations`, `Balanced`, `Steelman`, `FindGaps`, `PeerReview`
minimal (base layer)	"standard output format", "baseline reasoning shape"	`OutputFormat`, `Reasoning`, `StepByStep`, `Tone`, `Version`
meta	composing decorators or controlling their interaction	`Override`, `Chain`, `Conditional`, `Refine`, `Priority`, `BuildOn`, `Extension`

Note: the minimal category is NOT a "brevity" bucket - it's the required base layer of foundational decorators (OutputFormat, Reasoning, StepByStep, Tone, Version). Those names are reasoning-shaped but they live under minimal/ in the registry because they're the base layer every other decorator composes with. For terseness, use Concise or ELI5 from tone. For stepwise output, either ::StepByStep (minimal base-layer) or a reasoning pattern like ::TreeOfThought works.

**User prompt:** "Compare REST and GraphQL, including pros and cons in a table." **Intent:** reasoning + structure. **Suggestion:** `::Comparison` + `::TableFormat`.

**User prompt:** "What's 2+2?" **Intent:** none. Don't suggest decorators for trivial prompts - the decoration overhead outweighs the benefit.

Step 2: Pick 1-3 decorators

Use /decorate search <term> to confirm the decorator exists and to read its one-line description. Use /decorate preview <Name> to see the exact instruction text it expands into.

Rules of thumb:

Never more than 3 decorators stacked - they start to contradict each other.
Never stack two from the same category unless the category is explicitly combinable (e.g., Concise + StepByStep is fine; Detailed + Concise is not).
Prefer concrete decorators over meta ones. +++StepByStep usually beats +++Chain(steps=5).

Step 3: Decide the delivery method

Pattern	When to recommend
Inline (`::Name` at start of prompt)	One-off use, or when the user is already thinking about this specific prompt
Always-on (`/decorate always add <Name>`)	User indicates a persistent preference ("always be concise", "always show me the reasoning")
Auto mode (`/decorate auto on`)	User is exploring and wants the model to pick decorators for them
Auto one-shot (`/decorate auto once`)	User wants the selector to try, just for the next prompt, without committing

Step 4: Communicate the suggestion

Show the user the exact syntax they should type. Example output:

For this prompt, try:

    ::Comparison
    ::TableFormat
    Compare REST and GraphQL, including pros and cons.

The hook will expand those sigils into precise instructions before the
model sees the prompt.

If the user has never used decorators before, include a one-line pointer to /decorate help so they can discover the rest of the surface.

User Interaction

Use the AskUserQuestion tool when:

The intent is ambiguous

Question: "Your prompt could benefit from different decorator families. Which
flavour do you want?"
Options:
- "Concise + Structured (short, in a table)"
- "Detailed reasoning (why this is the right answer)"
- "Verification (cite sources, flag uncertainty)"
- "Let me pick from the catalogue"

The user asks "what decorators exist?"

Run /decorate list and relay the output. Do not try to memorise the catalogue - it's 100+ entries across more than a dozen categories and it changes over time; rely on /decorate list for accuracy.

The user wants auto-decorate but is worried about cost/latency

Question: "Auto-decorate adds ~400ms per prompt (Haiku round-trip). You
can pick per-prompt or session-wide."
Options:
- "Enable it for this one prompt only (/decorate auto once)"
- "Enable it for the whole session (/decorate auto on)"
- "Skip it - I'll pick decorators manually"

Failure Conditions

The suggestion is unacceptable if any of these hold:

The decorator name doesn't exist in the registry (always verify with /decorate list first).
More than 3 decorators are suggested.
Two decorators from the same narrow subcategory are stacked (e.g., two tone decorators).
The suggestion ignores the user's stated preference in their always-on config (check /decorate config before suggesting additions).

Output

When suggesting decorators, use this format:

**Suggested decorators:** `::Concise` + `::StepByStep(numbered=true)`

Rationale: your prompt asks for a short, structured walkthrough - those
two compose cleanly without contradicting each other.

Try:

    ::Concise
    ::StepByStep(numbered=true)
    <your original prompt>

References

Full catalogue: /decorate list (run this for current counts; the registry grows)
Preview a decorator: /decorate preview <Name>
Search by keyword: /decorate search <term>
Inline syntax reference: claude-code-plugin/README.md