ktg-plugin-marketplace/plugins/ultraplan-local/tests/fixtures/skill-factory/source-rejected.md

Output Styles Reference

Output styles let operators reshape how Claude Code presents its responses without changing the underlying behavior of the agent. They live as small markdown files in a known directory and bind by name. When a style is active, the runtime injects its directives into the system prompt area before the agent generates each turn. The agent treats those directives as binding instructions about format, voice, and rendering, and adapts its output accordingly.

The simplest style files are short. A handful of bullets describing the desired tone, target reading level, and any structural conventions like always using level-three headings or always wrapping commands in fenced code blocks. The runtime does not enforce any of these directives mechanically. It is the agent itself that reads the style file at turn time and chooses to comply. This means style enforcement is best-effort and degrades when the agent's primary task pulls strongly in a different direction.

A common pattern is the audience-specific style. A team might keep one style tuned for non-technical stakeholders, with longer prose, fewer code blocks, and a polite explanatory tone, alongside another style tuned for engineers, with terse responses, dense code, and minimal hedging. Operators switch styles per session depending on who is asking. The style file itself stays in version control so the conventions are reviewable and shareable.

Layering matters. Styles can be defined at the user level, the project level, or supplied by an installed plugin. When more than one style is active simultaneously, the runtime concatenates them in a documented order. There is no merging or conflict resolution. If two styles disagree about whether to use markdown tables, both directives are presented to the agent, which then has to pick one. Practitioners learn to keep styles narrow and orthogonal so that conflicts are rare.

A pitfall worth flagging is the temptation to encode behavior in styles when a hook or a skill would be more appropriate. Styles change presentation, not capability. If you find yourself writing imperative instructions like "always run the linter before reporting success," that belongs in a hook, not a style. Styles whose body looks like a procedure are usually mis-scoped and will not be followed reliably because the agent reads them as voice guidance rather than as obligations.

Performance is rarely an issue with styles. They add a small fixed cost to each turn for prompt assembly and that is essentially all. Unlike session-start hooks, they do not block first-turn rendering. Unlike subagent spawns, they do not introduce additional billable workers. The cost is purely the marginal tokens of the style body itself, multiplied by the number of turns in the session.

Testing styles is awkward because their effect is on free-form output. The standard approach is to keep a small set of canonical prompts and run them once with the style and once without, then eyeball the diff. Some teams have built lightweight golden-file harnesses for this, but no shared community tool exists. Most operators rely on quick manual checks during style development and trust the style to keep working in normal use.

Security boundaries are minimal because styles only inject text into the prompt area. They cannot run code, cannot read files, and cannot make network calls. The risk surface is therefore mostly social: a malicious style could try to coax the agent into ignoring safety instructions or revealing prompt-internal information. The mitigation is review discipline. Read the style body before installing a third-party plugin that ships one, the same way you would read any prompt-injecting artifact.

Observability is essentially DIY. The runtime does not log which style was active for which turn or whether the agent obeyed the style's directives. If you want to track style adherence, you will need to build it yourself, typically by sampling sessions and comparing the output to the style spec. A few teams have wired this into their prompt evaluation suites.

The flag landscape is mostly per-session. There is no global way to disable styles for a particular run, but operators can switch to a no-op style or remove the binding before launching. Some setups bind styles to environment variables so that a single export controls which voice the session uses, but this is a convention, not a runtime feature.

Looking ahead, the most-requested feature is conditional style activation: the ability to bind a style only when certain conditions are met, like when the working directory matches a pattern or when a specific user is operating the session. Currently this kind of selectivity has to be handled by manually swapping styles between sessions, which is friction operators would gladly trade for declarative bindings. A future runtime release may address this.

The takeaway is that styles are a low-risk, low-cost lever for tuning how the agent talks, and they pay off most when teams have multiple distinct audiences or when consistent voice across sessions matters for the brand or the team's external communication. Used within those constraints, they earn their keep without surprising anyone.