Outfitter Styleguide

Outfitter Styleguide

Craft-level guidance for Outfitter writing. This covers how to write — rhythm, metaphors, structural patterns.

For the philosophical foundation (why we write this way), load the outfitter-voice skill.

Write like someone who's genuinely excited to share what they discovered—while staying honest about rough edges.

The Core Stance

The Builder on the Trail

You're not a guru dispensing wisdom from a mountaintop. You're a fellow traveler who found a useful path and is sharing it with others still navigating.

• Problems are design challenges, not insurmountable obstacles
• Optimism is structural, but grounded in what actually works
• Cynicism is avoided—never tear down without offering a better alternative
• Focus on utility and durability, not hype

The "Product Person" Who Ships

Outfitter exists at the intersection of product thinking and engineering craft:

• Respect for engineering: use specific metrics because craft matters
• Focus on outcome: care about durable software, not code elegance for its own sake
• Not claiming expert status: empowered by new tools, learning in public

Agents as Readers

We write for Claude as much as we write for humans:

• Structure for machine readability, not just human skimming
• Examples are copy-paste runnable
• Errors and edge cases are explicit, not implied

Attention as Constraint

Every tool we build, every word we write, should respect the reader's time:

• Prioritize information density over word count
• If a sentence doesn't add value, delete it
• Serve the goal — voice is how we say things, not permission to say more
• The writing style is a recursive implementation of the product philosophy

Voice vs. Tone

Voice (always present):

• Curious practitioner
• Builder's mindset (even when learning)
• Respectful of reader's intelligence and time
• Sincere enthusiasm without self-importance
• Concrete specificity over abstraction

Tone (adjust per context):

• Playful when introducing tools
• Precise when documenting
• Earnest when mission-driven
• Technical without gatekeeping

The key tension: We care deeply about craft and ideas. We refuse to be precious about it.

The Expedition Layer

The expedition layer is a brand aesthetic, not a prose checklist. It should shape the feel of names, structure, and examples without turning every paragraph into metaphor.

Use expedition language literally when it's part of the product (for example, a command, package, or feature name). Otherwise, treat it as background texture: present when useful, invisible when forced.

Where It Shows Up Naturally

Practical Distinction

• If the thing is literally named scout, write scout.
• If the thing is not named scout, say "research" unless the metaphor genuinely improves understanding.
• Prefer clarity first; theme is a multiplier, not the main payload.

When to Skip It

• Technical specifications (just be precise)
• Error messages (just be clear)
• API documentation (just be accurate)
• When it would feel forced or cutesy

The Test

Would a thoughtful reader roll their eyes? If yes, drop the metaphor and say it straight.

Sentence Rhythm: Punch-and-Flow

The voice is engineered for readability. Ideas are "atomized" for digital consumption.

Four Sentence Types

The Rule

Every third or fourth sentence should act as a reset—short, punchy, direct. Uniform paragraph sludge loses readers.

Status Modulation

Mix high-status (authority) and low-status (trust) signals strategically.

High Status (Establish Credibility)

• Specific metrics: "5-50ms," "6ms warm cache," "100k tokens saved"
• Technical precision: terms like "latency," "index," "cache" used correctly
• Concrete examples over hand-waving

Low Status (Build Connection)

• Admitted struggles: "bugs galore," "countless hours lost"
• Builder's vulnerability: "first tool I've shipped despite five startups"
• Colloquial release valves: "not fully baked yet," "I actually laughed out loud"

The Dynamic

Elevate the reader through precision while leveling the field through honesty. Never lecture down. Position as a peer figuring it out alongside them.

Constraint: Don't over-credential. Let precision and comfort with tradeoffs signal competence; don't announce it.

Enthusiasm Calibration

Earned enthusiasm lands. Manufactured enthusiasm repels.

Allowed

• "I actually laughed out loud when I saw the result"
• "This is the part that changed everything for me"
• "Trust me—this is worth the setup"

Not Allowed

• "This is absolutely incredible!"
• "Game-changing innovation"
• "We are thrilled to announce"

The Test

Would you say this to a smart friend over coffee? If it sounds like marketing copy, rewrite it.

Banned Words & Substitutes

Rule: One well-placed superlative lands. Three reads as marketing.

Opening Moves

Pick exactly one:

• Scene → tension: Start grounded, then reveal the problem
• Vulnerability hook: Admit the struggle that led to the discovery
• Punchy declaration → why it matters: A clean statement, then human context
• Problem framing: State what's broken before offering the fix

Example (BLZ post)

"I've co-founded five startups... but the engineering? Always in someone else's hands."

Vulnerability first, then the journey.

Closing Moves

Pick exactly one:

• Invitation: "If you're building with agents, give it a shot"
• What's next: "We're still figuring out X, but here's where we're headed"
• Practical nudge: "Start with the simplest case and expand from there"
• Door left ajar: End with a question or possibility, not a summary

Not Allowed

• Empty summary of what was just said
• "In conclusion…"
• Marketing call-to-action ("Sign up now!")

Structural Signatures

• Headers as mini-theses: Not decorative—each header should be a claim or direction
• Signposting that moves: "But first…", "Here's the thing…", "So where does that leave us?"
• Parenthetical texture: Caveats, humanity, small admissions
• Context jumps: Quick explanations for unfamiliar terms, then back to momentum
• Bold used sparingly: For the single emphasis that matters

Content Modes

The goal of the content determines its shape. Match the container.

README / CLAUDE.md

• Expedition metaphors welcome where they clarify
• Focus on orientation and preparation
• Quick Start gets to code fast — context comes after
• "Here's what you need to know before diving in"

Blog Posts

• Full voice DNA applies
• Narrative arc: problem → journey → discovery → reflection
• Vulnerability + precision blend
• Technical without gatekeeping
• Room to breathe and explain the why

Announcements

• Lead with value, not company news
• "Here's what you can do now" over "We built X"
• Specifics over superlatives

Technical Docs

• Voice recedes; clarity leads
• Skip expedition metaphors
• Precision and completeness matter most
• Don't make people scroll past backstory to get the recipe

API Reference

• Precision over personality
• Just the facts
• Examples are copy-paste runnable

Anti-Patterns

Voice Violations

• Corporate-speak or press-release gloss
• Excessive hedging or qualification
• Lecturing or talking down
• Manufactured enthusiasm
• Vague abstractions without examples

Structural Violations

• Burying the lede
• Walls of text without signposts
• Over-formatting (headers as decoration)
• Ending with a thud instead of a door

Model-Specific Anti-Patterns

• Over-signposting ("Now…" spam)
• Generic "Tech Blogger" voice
• Preamble before getting to the point
• Empty concluding summaries

The Litmus Test

Before publishing, ask:

1. Would Matt say this to a smart friend over coffee?
2. Is there a concrete example within two paragraphs of any claim?
3. Does the ending open a door or close with a thud?
4. Would a reader roll their eyes at any metaphor?
5. Is enthusiasm earned or manufactured?

If any answer is wrong, revise.

References

• SAMPLES.md — Golden examples from Outfitter blog posts for pattern-matching