Agent preferences: user-configurable style guidance loaded into agent context

[tmustier]

Agent preferences: user-configurable style guidance loaded into agent context

Problem

AI agents producing slide content exhibit predictable stylistic patterns ("AI-isms") that make text feel generated rather than human-written. Currently there's no way for users to capture their style preferences so the agent can learn and adapt. Each session starts from zero.

Examples of common AI-isms that users might want to guide:

• Em-dashes — overused where colons, full stops, or sub-bullets would be cleaner
• "Not X, but Y" constructions — a common AI tell that sounds formulaic
• Hedging language — "it's important to note that", "it should be noted"
• Parallelism over-optimisation — forcing every bullet to start with the same part of speech

Proposed direction

Preferences file

A .clean-slides/preferences.md (or similar) that:

• Ships with sensible defaults when pptx init is run — a starting set of style guidance with brief explanation
• Gets loaded into agent context when the skill is invoked (the skill instructions reference it)
• Is written as guidance, not directives — "restraint in X makes text feel more natural" rather than "never use X", because rigid rules are brittle and context-dependent
• Survives upgrades — lives in .clean-slides/ (user's project directory), not in the package. pptx init should not overwrite an existing preferences file. pip install --upgrade and npm install don't touch it.

Example default content

# Style Preferences

Guidelines for AI agents generating slide content. Written as context rather than
rules — use judgement based on the specific slide and audience.

## Tone
- Professional but not stiff. Aim for the clarity of a well-written internal memo.
- Avoid hedging ("it is important to note", "it should be noted") — state the point directly.

## AI-isms to watch for
Restraint in the following makes text feel more natural:
- **Em-dashes** — where a colon, full stop, or sub-bullet could be cleaner instead
- **"Not X, but Y"** constructions — a common AI pattern that sounds formulaic when overused
- **Forced parallelism** — not every set of bullets needs identical grammatical structure
- **Superlatives and intensifiers** — "critical", "transformative", "unprecedented" lose impact when overused

## Formatting
- Prefer short, scannable text in cells — one idea per paragraph
- Use bullets sparingly; level-zero (no bullet) is often cleaner
- Bold for emphasis, not for structure — if everything is bold, nothing is

Agent memory loop

When the agent notices the user repeatedly editing out a pattern (or the user mentions a preference):

1. The agent should offer to add it to preferences: "I notice you've removed em-dashes from several cells — would you like me to add a note about this to your style preferences?"
2. If accepted, the agent appends to .clean-slides/preferences.md
3. The preferences are loaded on next invocation

This is an opt-in loop — the agent suggests, the user confirms.

Loading mechanism

The skill instructions (SKILL.md) should include a step like:

Before generating content, check for .clean-slides/preferences.md and incorporate
any style guidance into your approach.

The user can also view and edit preferences directly:

cat .clean-slides/preferences.md        # view
$EDITOR .clean-slides/preferences.md    # edit

Design principles

• Guidance over directives: "restraint in X" is more robust than "never use X" because the agent can judge context. A directive like "avoid em-dashes" will produce awkward workarounds; guidance like "em-dashes are an AI tell — consider alternatives" produces better judgement.
• Discoverable: users should know the file exists and how to edit it. pptx init should mention it.
• Non-destructive: upgrades never overwrite user preferences. If the default template evolves, the user can manually merge or regenerate.

Acceptance criteria

• pptx init creates .clean-slides/preferences.md with sensible defaults (does not overwrite existing)
• SKILL.md references the preferences file and instructs agents to load it
• Default content covers common AI-isms with guidance framing
• User can view and edit preferences with standard tools
• Package upgrades do not overwrite existing preferences