Internal Outfitter development skills for documentation, agent setup, and project conventions

version
0.4.2

Install

/plugin install internal@outfitter-internal

Run it inside Claude Code after adding the marketplace with /plugin marketplace add outfitter-dev/agents-internal.

Contents

Discovered from source

Skills 8

Documentation for Agents

Structure and patterns for documentation that AI agents consume — the files and directories that help Claude, Codex, and other agents understand and work with your project.

For human-facing documentation (READMEs, guides, API docs), load the internal:docs-write skill.

File Architecture

The recommended setup separates tool-agnostic agent guidelines from tool-specific configuration:

project/
├── AGENTS.md              # Canonical agent instructions (tool-agnostic)
├── CLAUDE.md              # Entry point that @-mentions AGENTS.md
└── .claude/
    ├── CLAUDE.md          # Claude-specific instructions
    ├── commands/          # Slash commands
    ├── skills/            # Project-specific skills
    ├── rules/             # Modular rule files
    └── settings.json      # Permissions, MCP servers

Why This Structure?

  • AGENTS.md works across tools (Claude, Codex, Cursor, etc.)
  • @-mentions avoid duplication and keep CLAUDE.md minimal
  • .claude/ holds Claude-specific extensions without polluting shared docs
  • Modular rules allow topic-specific guidance without bloating main files

AGENTS.md

The canonical source of agent instructions. Tool-agnostic — works for Claude, Codex, and other AI assistants.

Location: Project root

Purpose: Project context, conventions, and guidelines that any AI agent should follow.

Structure Template

# AGENTS.md

Guidelines for AI agents and developers working in this repository.

## Project Overview

Brief description of what this project does and its current status.

## Project Structure

- `src/` — Source code
- `tests/` — Test files
- `docs/` — Documentation

## Commands

\`\`\`bash
bun test              # Run tests
bun run build         # Build project
bun run lint          # Lint and format
\`\`\`

## Architecture

Key architectural decisions and patterns used in this codebase.

## Development Principles

Core principles: TDD, error handling patterns, dependency policies.

## Code Style

Language-specific conventions, formatting rules, naming patterns.

## Testing

Test runner, file locations, coverage expectations.

## Git Workflow

Branch naming, commit conventions, PR process.

What Belongs in AGENTS.md

IncludeExclude
Project structure overviewTool-specific instructions
Key commandsClaude task management
Architectural patternsCodex sandbox config
Development principlesMCP server setup
Code style conventionsIDE settings
Testing approach
Git workflow

Length Guidelines

  • Target: 100-300 lines
  • Maximum: 500 lines
  • Principle: Comprehensive but scannable — agents should find what they need quickly

CLAUDE.md (Root)

Minimal entry point that @-mentions other files. Claude Code reads this first.

Location: Project root

Purpose: Bootstrap Claude's context by pointing to the right files.

Recommended Pattern

# CLAUDE.md

This file provides AI agents with project-specific context and conventions.

@.claude/CLAUDE.md
@AGENTS.md

That's it. Keep the root CLAUDE.md minimal.

Why @-mentions Over Symlinks?

Previously, some projects used symlinks between CLAUDE.md and AGENTS.md. Don't do this.

Problems with symlinks:

  • Git treats them inconsistently across platforms
  • Some tools don't follow symlinks
  • Confusing when editing — which file is canonical?
  • Breaks when repo is cloned to paths with different structures

The @-mention pattern is explicit, portable, and clear about which file is authoritative.

.claude/CLAUDE.md

Claude-specific instructions that don't apply to other tools.

Location: .claude/CLAUDE.md

Purpose: Claude Code features, task management, tool-specific guidance.

Example Content

# Claude-Specific Guidance

## Task Management

Use the task tools to track work across context windows.

### Creating Tasks

Use `TaskCreate` for multi-step work:
- `subject`: Imperative form ("Run tests")
- `activeForm`: Present continuous ("Running tests")
- `description`: Detailed requirements

### Best Practices

- Create tasks immediately when receiving multi-step instructions
- Keep exactly one task `in_progress` at a time
- Never mark completed if tests fail

## Preferred Tools

- Use `gt` for version control, not raw `git`
- Prefer `Grep` tool over bash grep
- Use `Read` tool instead of `cat`

What Belongs in .claude/CLAUDE.md

IncludeExclude
Task management patternsProject architecture
Claude-specific tool preferencesCode style (goes in AGENTS.md)
MCP server usageTesting approach
Subagent coordinationGit workflow

.claude/rules/

Modular, topic-specific rule files. Auto-loaded into Claude's context.

Location: .claude/rules/*.md

Purpose: Focused guidance on specific topics — language conventions, testing patterns, API standards.

When to Use Rules Files

Use .claude/rules/ for:

  • Language-specific guidelines (TYPESCRIPT.md, RUST.md)
  • Testing conventions (TESTING.md)
  • API standards (API.md)
  • Security requirements (SECURITY.md)

Paths Frontmatter

Rules can be scoped to specific file patterns:

---
paths:
  - "**/*.ts"
  - "**/*.tsx"
---

# TypeScript Conventions

Use strict mode. Avoid `any`. Prefer `unknown` for truly unknown types.

This rule only loads when working with TypeScript files.

Codex Compatibility Note

Codex CLI doesn't support .claude/rules/ or paths frontmatter. Keep critical conventions in AGENTS.md to ensure all tools see them.

Guidance: Use rules files sparingly. If a convention matters for all agents, put it in AGENTS.md. Reserve rules files for Claude-specific enhancements that won't break the experience for other tools.

Directory Structure: .claude/

.claude/
├── CLAUDE.md           # Claude-specific instructions
├── commands/           # Slash commands
│   ├── build.md
│   ├── test.md
│   └── deploy.md
├── skills/             # Project-specific skills
│   └── local-skill/
│       └── SKILL.md
├── rules/              # Modular rule files
│   ├── TYPESCRIPT.md
│   ├── TESTING.md
│   └── SECURITY.md
├── hooks/              # Event hooks
│   └── hooks.json
└── settings.json       # Permissions, MCP servers
DirectoryPurpose
commands/User-invocable slash commands (/build, /test)
skills/Project-specific skills loaded on activation
rules/Topic-specific convention files
hooks/Event handlers for tool calls and lifecycle

Writing for Agent Consumption

When writing content that agents will parse:

Structure for Machines

## Good: Explicit structure

| Command | Description |
|---------|-------------|
| `bun test` | Run tests |
| `bun build` | Build project |

## Bad: Prose-heavy

To run tests, you can use the bun test command. For building,
there's bun build which will compile everything.

Be Explicit About Types

## Good: Type information clear

The `timeout` option accepts a `number` in milliseconds.
Default: `30000`. Range: `1000-300000`.

## Bad: Ambiguous

Set timeout to control how long operations wait.

Document Error Conditions

## Good: Errors are first-class

| Error | Cause | Resolution |
|-------|-------|------------|
| `CONFIG_NOT_FOUND` | Missing config file | Run `init` first |
| `INVALID_FORMAT` | Malformed input | Check input schema |

## Bad: Errors as afterthought

This might fail if config is missing.

Avoid Ambiguous Pronouns

## Good: Specific nouns

The `UserService` validates input. The service returns
a `Result<User, ValidationError>`.

## Bad: Ambiguous "it"

The service validates input. It returns a result if it succeeds.

Tables Over Prose

Agents parse tables more reliably than paragraphs.

Explicit Over Implicit

State conventions directly. Don't assume agents will infer them.

Concision Over Grammar

Sacrifice grammar for concision. Agents parse tokens, not prose. "Use strict mode" beats "You should always make sure to use strict mode."

Workflow

When this skill is activated, assess the current state and present options to the user using AskUserQuestion:

1. Scan for existing AGENTS.md, CLAUDE.md, .claude/ structure
2. Compare against recommended patterns
3. Present options via AskUserQuestion tool:
   - Audit: Review current docs against patterns
   - Restructure: Reorganize to match recommended structure
   - Enhance: Keep structure, improve content
   - Create: Build missing components from scratch
4. Execute chosen action
5. Validate result against guidelines

Always use AskUserQuestion when the user needs to choose between approaches. Don't list options in prose — use the tool for interactive decisions.

Guidelines

When creating or reviewing agent-facing documentation:

  • ALWAYS create AGENTS.md with tool-agnostic guidelines at project root
  • ALWAYS use @-mentions in root CLAUDE.md to reference other files
  • ALWAYS keep .claude/CLAUDE.md focused on Claude-specific content only
  • ALWAYS structure content for quick scanning — tables over prose
  • ALWAYS state conventions explicitly — agents don't infer
  • NEVER use symlinks between CLAUDE.md and AGENTS.md
  • NEVER put critical conventions only in .claude/rules/ — Codex won't see them
  • NEVER duplicate content across files — link instead

References

  • MIGRATION.md — Migrate existing setups to the recommended pattern

Agent Setup

Check and configure outfitter marketplaces in a project.

Check Current Status

Checks both project (.claude/settings.json) and user (~/.claude/settings.json) levels.

!bun ${CLAUDE_PLUGIN_ROOT}/skills/agent-setup/scripts/check-outfitter.ts .

Marketplaces

AliasRepoRequired Plugin
outfitteroutfitter-dev/agentsoutfitter@outfitter
outfitter-internaloutfitter-dev/agents-internaloutfitter-dev@outfitter-internal

Optional Plugins

From outfitter marketplace:

PluginPurpose
gtGraphite stacked PR workflows
butGitButler virtual branch workflows
cli-devCLI development patterns

Required Setup

{
  "extraKnownMarketplaces": {
    "outfitter": {
      "source": { "source": "github", "repo": "outfitter-dev/agents" }
    },
    "outfitter-internal": {
      "source": { "source": "github", "repo": "outfitter-dev/agents-internal" }
    }
  },
  "enabledPlugins": {
    "outfitter@outfitter": true,
    "outfitter-dev@outfitter-internal": true
  }
}

Full Setup

{
  "extraKnownMarketplaces": {
    "outfitter": {
      "source": { "source": "github", "repo": "outfitter-dev/agents" }
    },
    "outfitter-internal": {
      "source": { "source": "github", "repo": "outfitter-dev/agents-internal" }
    }
  },
  "enabledPlugins": {
    "outfitter@outfitter": true,
    "outfitter-dev@outfitter-internal": true,
    "gt@outfitter": true,
    "but@outfitter": true,
    "cli-dev@outfitter": true
  }
}

Documentation Check

Rigorous quality gate for documentation. Focused on correctness, completeness, and comprehensiveness — not just voice and style.

Usage

/docs-check [focus]

Examples

/docs-check                              # Full quality gate
/docs-check focus on code examples       # Verify examples run
/docs-check check API completeness       # Parameter coverage
/docs-check are all links valid?         # Link check
/docs-check just the Quick Start         # Section-specific

Arguments

Focus: $ARGUMENTS

Use arguments to narrow the scope:

Argument TypeExampleBehavior
Section namejust the Quick StartAudit only that section
Quality dimensionfocus on correctnessPrioritize that checklist
Specific questionare the code examples runnable?Answer directly with evidence
None provided(empty)Run full checklist across all dimensions

Verification Checklist

Work through each dimension. For each item, document: PASS/FAIL + evidence.

Correctness (accuracy)

CheckHow to Verify
Code examples runExtract and execute each example. Report errors verbatim.
API signatures matchCompare documented signatures against source code.
Links resolveCheck each link target exists (relative paths, anchors, URLs).
Technical claims accurateCross-reference against implementation or authoritative source.
Versions currentVerify version numbers match package.json, Cargo.toml, etc.

Completeness (nothing missing)

CheckHow to Verify
Required sections presentCompare against applicable template (README, API ref, guide).
Parameters documentedEach param has: type, purpose, constraints, default value.
Error scenarios coveredDocument what happens when things go wrong.
Edge cases addressedEmpty inputs, nulls, boundaries, concurrent access.
Success and failure examplesShow both happy path and error handling.

Comprehensiveness (depth)

CheckHow to Verify
Common use casesList 3-5 typical scenarios; verify each is addressed.
Migration pathsBreaking changes include upgrade instructions.
Cross-referencesRelated docs linked where helpful.
Agent-friendlyStructured for AI consumption (clear headers, examples).
TroubleshootingCommon issues and solutions documented.

Execution

  1. Identify target — What documentation is being checked?
  2. Run checks — Work through the checklist, executing verification steps
  3. Collect evidence — Note specific line numbers, error messages, missing items
  4. Classify issues — Blocking (must fix) vs. suggestions (nice to have)
  5. Report — Structured output per format below

Output Format

# Documentation Check: {doc-name}

**Verdict**: PASS | NEEDS WORK | BLOCKED
**Blocking issues**: {count}
**Suggestions**: {count}

## Blocking Issues (must fix)

1. **{Check name}**: {Issue description}
   - Location: {file:line or section}
   - Evidence: {error message, mismatch, etc.}
   - Fix: {specific action to resolve}

## Suggestions (nice to have)

1. {Improvement with rationale}

## Passed Checks

- {List of checks that passed}

## Summary

{One sentence: ready to publish or what must be addressed first}

When to Use

  • Before merging documentation PRs
  • Before publishing READMEs to new packages
  • Quarterly documentation audits
  • After major feature changes

Relationship with docs-review

For combined voice/style and technical verification, load both this skill and the internal:docs-review skill.

Dimensiondocs-reviewdocs-check
FocusVoice, style, structureCorrectness, completeness
Question"Does it sound right?""Is it accurate and complete?"
ApproachSubjective assessmentObjective verification
OutputEditorial feedbackPass/fail with evidence
SpeedQuick passThorough audit

When to use each:

  • docs-review — Polishing prose, checking tone, improving flow
  • docs-check — Quality gate before merge, verifying technical accuracy
  • Both — Full documentation audit (load both skills)

Documentation Review

Review the current document against Outfitter standards for voice, style, and structure.

Review Direction

$ARGUMENTS

If direction is provided above, focus on that specific aspect. Otherwise, perform a general review across all dimensions.

Review Criteria

Voice

Does it sound like Outfitter?

  • Confident, opinionated stance
  • Agents as first-class consumers
  • Plain language over jargon

Style

Is the craft right?

  • Punch-and-flow rhythm (short + long sentences)
  • Earned enthusiasm (backed by substance)
  • Strong opening and closing

Structure

Does it follow documentation patterns?

  • Appropriate template usage
  • Complete, runnable examples
  • Correct heading hierarchy (h1 > h2 > h3)

Output Format

Provide your review in this format:

Status: Ready | Needs Work

Summary: One sentence overall assessment.

Issues (if any):

  • [Location] Issue description and suggested fix

Strengths:

  • What works well

If the document is ready, say so briefly. If it needs work, be specific about locations and fixes.

Documentation Standards

Structure and templates for project documentation — the human-facing docs that help developers understand and use your project.

This skill covers what to include and where it goes. For how to write it:

  • Load the internal:styleguide skill for sentence rhythm, metaphors, structural moves
  • Load the internal:voice skill for philosophical foundation (apply as review pass)

For agent-specific documentation (CLAUDE.md, AGENTS.md), load the internal:agent-docs skill.

Documentation Hierarchy

Documentation is prioritized in this order:

  1. Types — Self-documenting code through TypeScript types
  2. Inline comments — TSDoc/JSDoc for non-obvious decisions
  3. docs/ — Broader architectural and reference material

All three levels matter. Types express intent through code, comments explain why, and docs provide context.

Project Directory Structure

Standardized directory layout for documentation across repositories.

Root-Level Files

FilePurpose
README.mdEntry point for humans — quick start, links to docs
CONTRIBUTING.mdContribution guidelines (if applicable)
CHANGELOG.mdVersion history (auto-generated preferred)

Standard Directories

project/
└── docs/
    ├── architecture/        # System design, ADRs
    ├── api/                 # API reference (if applicable)
    ├── cli/                 # CLI command reference
    ├── guides/              # How-to guides, tutorials
    └── development/         # Dev setup, workflows

Directory Purpose

DirectoryContent
architecture/System design docs, Architecture Decision Records (ADRs), diagrams
api/API reference, endpoint documentation, type definitions
cli/Command reference, flags, usage examples, exit codes
guides/How-to tutorials, walkthroughs, use-case guides
development/Contributing setup, local dev, testing, release process

Source of Truth Principle

Each type of documentation should have one canonical location:

  • API reference → Generated from code or docs/api/
  • CLI reference → docs/cli/ or generated from help text
  • Architecture decisions → docs/architecture/ or ADRs

Avoid duplicating content across locations. Link instead of copy.

README Standards

READMEs are the entry point for new contributors. Keep them focused and scannable.

Structure Template

# Project Name

One-line description of what this does.

## Why [Project Name]?

Brief explanation of the problem this solves (2-3 sentences).

## Quick Start

Minimal steps to get running:

\`\`\`bash
# Installation
bun add project-name

# Basic usage
bun run project-name
\`\`\`

## Features

- Feature 1 — brief description
- Feature 2 — brief description
- Feature 3 — brief description

## Documentation

- [Getting Started](./docs/guides/getting-started.md)
- [API Reference](./docs/api/)
- [CLI Reference](./docs/cli/)
- [Architecture](./docs/architecture/)

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## License

MIT

Length Guidelines

  • Target: 150-250 lines
  • Maximum: 400 lines (beyond this, extract to docs/)
  • Minimum: 50 lines (needs at least: description, install, usage)
  • Flexible: As long as needed for pain, value prop, quick starts, doc pointers

What Belongs in README vs docs/

READMEdocs/
Quick start (5-10 steps max)Full tutorials
Feature list (bullet points)Feature deep-dives
Installation optionsConfiguration reference
Links to detailed docsThe detailed docs themselves

Leading Section Pattern

Choose based on project type:

  • Libraries/Tools: Lead with "Quick Start" — users want to try it immediately
  • Frameworks/Platforms: Lead with "Why X?" — users need to understand the value proposition
  • Internal Tools: Lead with "Usage" — users already know why, they need how

Stability Tier Labels

When documenting packages or components with different maturity levels, use these labels:

LabelMeaningGuidance
StableAPIs locked, breaking changes rareSafe to depend on
ActiveAPIs evolving based on usageWatch for updates
EarlyAPIs will change, not production-readyUse with caution

Avoid metaphorical labels (Cold/Warm/Hot, etc.) — literal labels require no interpretation.

Quick Start Best Practices

  1. Make it copy-paste runnable. Use heredoc format when showing file creation:

    cat > example.ts << 'EOF'
    import { ok, err } from '@org/contracts';
    // ... code
    EOF
    bun run example.ts
    
  2. Show output, including errors. Demonstrate both success and failure:

    $ my-tool search --query "test"
    Found: [ "result-1", "result-2" ]
    
    $ my-tool search
    Error [validation]: Query is required
    

    Showing error output proves your error handling works.

  3. End with a memorable closer. After the output block, add a confident one-liner:

    **Output:**
    \`\`\`
    Found: [ "result-1", "result-2" ]
    \`\`\`
    
    Done. You're building type-safe infrastructure.
    
  4. Use domain-relevant examples. Avoid generic "Hello, World!" — use examples that demonstrate actual value.

CLI Documentation

For projects with CLIs, document commands in docs/cli/.

Command Reference Template

# command-name

Brief description of what this command does.

## Synopsis

\`\`\`
my-tool command [options] <required-arg> [optional-arg]
\`\`\`

## Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `<required-arg>` | Yes | What this argument controls |
| `[optional-arg]` | No | What this optional argument does |

## Options

| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--verbose` | `-v` | `false` | Enable verbose output |
| `--output` | `-o` | `stdout` | Output destination |

## Examples

\`\`\`bash
# Basic usage
my-tool command input.txt

# With options
my-tool command -v --output result.json input.txt
\`\`\`

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error |
| `2` | Invalid arguments |

Document Structure

Every technical document should include:

# [Feature/Component Name]

Brief description of what this covers and why it matters.

## Overview

High-level explanation of the concept or component.

## Usage

How to use this in practice, with examples.

## API Reference (if applicable)

Detailed parameter and return value documentation.

## Examples

Complete, working code examples.

## Common Patterns

Typical use cases and recommended approaches.

## Troubleshooting (if applicable)

Common issues and their solutions.

Heading Hierarchy

  • H1 (#): Document title only
  • H2 (##): Major sections
  • H3 (###): Subsections
  • H4 (####): Specific topics within subsections
  • Avoid deeper nesting than H4

Code Examples

Requirements

  • Include all necessary imports
  • Show both definition and usage
  • Add brief comments for complex logic
  • Ensure examples are runnable
  • Test examples before documenting

Good Example

interface UserConfig {
  timeout: number;
  retries: number;
}

function configureUser(options: UserConfig): void {
  // Validate timeout is positive
  if (options.timeout <= 0) {
    throw new Error('Timeout must be positive');
  }
  applyConfig(options);
}

// Usage
configureUser({ timeout: 5000, retries: 3 });

Bad Example

// Incomplete, lacks context
function configure(opts) {
  // ...
}

API Documentation

Function Documentation

/**
 * Processes user data according to specified rules.
 *
 * @param userData - The raw user data to process
 * @param rules - Processing rules to apply
 * @returns Processed user data with applied transformations
 *
 * @example
 * ```typescript
 * const processed = processUser(
 *   { name: 'John', age: 30 },
 *   { uppercase: true }
 * );
 * // Returns: { name: 'JOHN', age: 30 }
 * ```
 *
 * @throws {ValidationError} When userData is invalid
 * @throws {RuleError} When rules cannot be applied
 */
function processUser(userData: UserData, rules: ProcessRules): ProcessedUser

Parameter Documentation

Always document:

  • Type: Explicit TypeScript types
  • Purpose: What the parameter controls
  • Constraints: Valid ranges, formats, or values
  • Defaults: If applicable
  • Examples: For complex types

Configuration Tables

| Option    | Type      | Default | Description                     |
|-----------|-----------|---------|--------------------------------|
| `port`    | `number`  | `3000`  | Server port                    |
| `timeout` | `number`  | `30000` | Request timeout in milliseconds |
| `debug`   | `boolean` | `false` | Enable debug logging           |

Maintenance

  1. Update with code: Documentation changes must accompany code changes
  2. Review regularly: Audit documentation quarterly for accuracy
  3. Remove outdated content: Delete obsolete information rather than marking as deprecated
  4. Version appropriately: Clearly document breaking changes and migration paths
  5. Test examples: Verify all code examples work with current versions

Review Checklist

Before finalizing documentation:

  • All code examples are tested and working
  • Technical terms are defined or linked
  • Structure follows the standard template
  • No outdated information remains
  • Examples cover common use cases
  • Error scenarios are documented
  • API signatures are complete
  • Cross-references are valid

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 internal: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 metaphor gives Outfitter texture—but it's earned, not decorative. Use it when it clarifies; skip it when it obscures.

When It Works

MetaphorUse When
"Trail" / "Path"Describing established patterns worth following
"Terrain"The technical environment or problem space
"Gear" / "Provisions"Tools, dependencies, configurations
"Base camp"Project setup, repository structure
"Scout"Research, exploration, proof-of-concept
"Expedition"A significant project or initiative

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

TypeFunctionExample
Setup (Flow)Draws reader in, establishes context"Recently we've seen agents waste 60,000+ tokens per documentation lookup…"
Pivot (Hinge)Connects thought to consequence; uses colons or dashes"The result: search in 5-50ms, not 5-50 seconds."
Punch (Impact)Short, direct; resets attention"That changed everything."
Aside (Meta)Parenthetical; adds intimacy"…context engineering (more on that later)…"

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

Instead of...Try...
"game-changing"describe the actual change
"seamless""I didn't have to…"
"incredible/amazing"a concrete fact or benchmark
"revolutionary""new capability: …"
"We are excited to share"Start with the value
"best-in-class"specific comparison
"synergy"never

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

Use Bun

Bun-first philosophy: prefer native APIs over external packages.

<when_to_use>

  • Auditing existing projects for Bun migration opportunities
  • Starting new TypeScript projects
  • Evaluating whether to add a dependency
  • Reviewing code that uses Node.js APIs
  • Cleaning up package.json bloat

Boundary: This skill covers when to use Bun and what it replaces. For detailed Bun API patterns and implementation examples, load the outfitter:bun-dev skill instead.

</when_to_use>

CLI Commands

Use Bun directly instead of Node.js tooling:

Instead ofUse
node file.ts or ts-node file.tsbun file.ts
jest or vitestbun test
webpack or esbuild (CLI)bun build
npm install / yarn / pnpmbun install
npm run scriptbun run script
npx packagebunx package
nodemonbun --watch
node --env-file=.envbun (auto-loads .env)

Decision Framework

Before adding a dependency, follow this hierarchy:

Need functionality
│
├─► Does Bun have a built-in API?
│   └─► YES → Use it directly
│
├─► Can you wrap a Bun primitive?
│   └─► YES → Thin abstraction over Bun API
│
└─► External package (last resort)
    └─► Document why Bun couldn't do it

Evaluation Checklist

  1. Check Bun docs first: https://bun.sh/docs
  2. Search for Bun. or bun: in docs
  3. Test if Node.js API you're using has faster Bun equivalent
  4. If adding package, verify Bun doesn't cover it natively

When Packages Are Justified

  • Framework-level abstractions (Hono, TanStack Router)
  • Domain-specific logic (Zod schemas, date-fns)
  • Protocol implementations Bun doesn't cover
  • Battle-tested crypto beyond basic hashing

Document exceptions with a code comment:

// Using date-fns: Bun has no date manipulation APIs
import { format, addDays } from 'date-fns';

Quick Reference

Bun APIs organized by category. Check these before reaching for npm.

Testing

Bun APIReplaces
bun:testjest, vitest, mocha
expect()chai, expect.js
import { describe, test, expect } from 'bun:test';

Database & Storage

Bun APIReplaces
bun:sqlitebetter-sqlite3, sql.js
Bun.sqlpg, postgres.js, mysql2
Bun.redisioredis, redis
Bun.s3@aws-sdk/client-s3
import { Database } from 'bun:sqlite';
const client = Bun.redis();
const bucket = Bun.s3('my-bucket');

Networking

Bun APIReplaces
Bun.listen()net.createServer
Bun.connect()net.connect
Bun.udpSocket()dgram.createSocket
Bun.dnsdns.lookup

HTTP

Bun APIReplaces
Bun.serve()express, fastify, http
Bun.fetch()node-fetch, axios, got
Bun.serve({ port: 3000, fetch: (req) => new Response('ok') });

Shell & Process

Bun APIReplaces
Bun.$execa, shelljs, zx
Bun.spawn()child_process.spawn
Bun.spawnSync()child_process.spawnSync
import { $ } from 'bun';
await $`ls -la`;

File System

Bun APIReplaces
Bun.file()fs.readFile, fs-extra
Bun.write()fs.writeFile
file.exists()fs.existsSync
file.stream()fs.createReadStream
const content = await Bun.file('./data.json').json();
await Bun.write('./out.txt', content);

Utilities

Bun APIReplaces
Bun.password.hash()bcrypt, argon2
Bun.hash()xxhash, murmur, crc32
Bun.CryptoHashercrypto.createHash
Bun.Globglob, fast-glob, minimatch
Bun.semversemver
Bun.YAML.parse()js-yaml, yaml
Bun.TOML.parse()toml
Bun.gzipSync()zlib, pako
Bun.zstdCompressSync()zstd-codec
Bun.Archivetar, archiver
Bun.sleep()delay, timers-promises
Bun.deepEquals()lodash.isEqual, deep-equal
Bun.escapeHTML()escape-html
Bun.stringWidth()string-width
Bun.Cookiecookie, tough-cookie
Bun.randomUUIDv7()uuid
Bun.which()which
const hash = await Bun.password.hash(password, { algorithm: 'argon2id' });
const glob = new Bun.Glob('**/*.ts');
const valid = Bun.semver.satisfies('1.2.3', '>=1.0.0');

Bundling

Bun APIReplaces
Bun.build()esbuild, rollup, webpack
bun build --compilepkg, nexe
bun build ./index.ts --outfile dist/bundle.js --minify

Frontend Development

Bun.serve() supports HTML imports with automatic bundling. No Vite/Webpack needed.

// server.ts
import index from "./index.html";

Bun.serve({
  routes: {
    "/": index,
    "/api/data": (req) => Response.json({ ok: true }),
  },
  development: { hmr: true, console: true },
});

HTML files can import .tsx/.jsx/.ts directly:

<!-- index.html -->
<html>
  <body>
    <div id="root"></div>
    <script type="module" src="./app.tsx"></script>
  </body>
</html>

Run with hot reloading:

bun --hot server.ts

Audit Command

Scan a codebase for Bun migration opportunities using the bundled audit script.

# From the skill directory (or adjust path as needed)
bun ./scripts/audit-bun-usage.ts [path]

# JSON output (default) - pipe to jq, use in CI
bun ./scripts/audit-bun-usage.ts ./my-project

# Markdown output - human readable
bun ./scripts/audit-bun-usage.ts ./my-project --format=md

The audit identifies:

  • npm packages replaceable by Bun built-ins
  • Node.js imports with Bun equivalents
  • Config files for tools Bun replaces
  • Files already using Bun APIs (positive signal)

Common Migrations

From Express/Fastify

// Before: Express
import express from 'express';
const app = express();
app.get('/', (req, res) => res.send('ok'));
app.listen(3000);

// After: Bun.serve + Hono
import { Hono } from 'hono';
const app = new Hono().get('/', (c) => c.text('ok'));
Bun.serve({ port: 3000, fetch: app.fetch });

From Jest/Vitest

// Before: Jest
import { describe, it, expect } from '@jest/globals';

// After: bun:test (drop-in compatible)
import { describe, it, expect } from 'bun:test';

From better-sqlite3

// Before
import Database from 'better-sqlite3';

// After (same API)
import { Database } from 'bun:sqlite';

From bcrypt

// Before
import bcrypt from 'bcrypt';
const hash = await bcrypt.hash(password, 10);

// After
const hash = await Bun.password.hash(password, { algorithm: 'argon2id' });

From execa/shelljs

// Before
import { execa } from 'execa';
const { stdout } = await execa('ls', ['-la']);

// After
import { $ } from 'bun';
const result = await $`ls -la`;
console.log(result.text());

ALWAYS:

  • Check Bun docs before adding any dependency
  • Use Bun.file/Bun.write over fs module
  • Use bun:test for testing (Jest-compatible)
  • Use bun:sqlite for SQLite (better-sqlite3 compatible)
  • Use Bun.password for password hashing
  • Use Bun.$ for shell commands

NEVER:

  • Add packages that duplicate Bun built-ins without documenting why
  • Use node-fetch when Bun.fetch exists
  • Use bcrypt when Bun.password exists
  • Use fs when Bun.file/Bun.write exists
  • Use child_process when Bun.$/Bun.spawn exists

DOCUMENT:

  • Why a package is needed when Bun alternative exists
  • Bun limitations encountered (helps track what to migrate later)
  • Exceptions in code comments for future audits

Related skills:

  • outfitter:bun-dev — Detailed Bun API patterns, implementation examples, testing strategies
  • outfitter:typescript-dev — TypeScript patterns for Bun projects, strict typing, Zod validation

Outfitter Voice

Outfitter writes like it means it. We're unapologetically opinionated — not because we think we're always right, but because wishy-washy tools make for wishy-washy software. If we've made a choice, we'll tell you why and stand behind it.

Quick Reference

PrincipleIn Practice
OpinionatedState choices clearly. Explain why. Don't hedge.
Agent-firstStructure for machines. Runnable examples. Typed errors.
Goal-servingMatch voice to container. Quick starts are quick.
Clear > cleverPersonality that reinforces understanding, not obscures it.
Plain languageSave generics for code. Use words people say.
Earned confidenceClaims backed by examples, benchmarks, tests.
Ownership stanceFirst-person "we". Possessive when it fits.

Agents at Every Step

We build with agents at every step of the way, and we're explicit about it. Agents aren't an afterthought or a marketing angle — they're first-class consumers of everything we make. When we write, we're writing for Claude as much as we're writing for you.

This shapes everything:

  • Documentation is structured for machine readability, not just human skimming
  • Rules aren't just stated — they're codified, tested, and enforced
  • Errors are typed and explicit, because agents need to handle them too
  • Examples are copy-paste runnable, because that's how agents learn

Serve the Goal

Voice is how we say things, not permission to say more.

If someone needs a code example, give them the code example. If they need a quick answer, give them the quick answer. Don't make people scroll past your life story to get the recipe.

The goal of the content determines its shape:

  • Quick Start — Get to code fast. Context comes after, if at all.
  • Philosophy section — Room to breathe. Explain the why.
  • API reference — Precision over personality. Just the facts.
  • Blog post — Full voice. Narrative, personality, earned enthusiasm.

Match the container. A README Quick Start and a blog post have different jobs.

Clear Beats Clever — But Personality Matters

Default to clarity. When established conventions exist, follow them.

But clever can be clear when it reinforces the mental model:

  • A breadcrumb tool called "crumbs" → crumb drop has personality without sacrificing meaning. crumb new is functional, but forgettable.
  • Ranger, Firewatch, Waymark — names that evoke what they do.
  • "Done. You're building type-safe infrastructure." — confident, memorable.

Clever fails when it requires translation:

  • Cold/Warm/Hot for stability tiers → "Cold means... frozen means... stable?" Just say Stable.
  • Jargon that sounds smart but means nothing to newcomers.

The test: Does the cleverness help you understand, or make you pause to decode?

Reinforce the vibe. Don't invent vocabulary.

Plain Language Over Jargon

"Typed errors instead of throwing" lands better than Result<T, E> in prose.

Save the generics for code blocks. When explaining concepts, use words people actually say. Technical precision matters in code; human clarity matters in explanation.

This doesn't mean dumbing down. It means choosing the right level of abstraction for the medium.

Vibes Matter, But So Does Verification

We care about how things feel, but we don't trust feelings alone.

If a rule matters, it's codified, tested, and enforced. Opinions without teeth are just suggestions. We don't say "prefer X" — we lint for it, test for it, fail builds over it.

This applies to voice too. If we claim something is simple, there's a working example. If we claim something is fast, there's a benchmark. Earned confidence, not asserted confidence.

The Ownership Stance

Outfitter takes ownership. First-person "we" when speaking as the project. Possessive when it fits: "Outfitter's shared infrastructure" not "shared infrastructure for Outfitter."

We're unapologetically opinionated about:

  • Correctness over convenience — Explicit errors, strict types, tests first
  • Agents as consumers — Not an afterthought, a design constraint
  • Intentional craft — Built deliberately, not accumulated accidentally

We're not hedging. We're not "just a simple tool." We're building something with purpose.

What This Isn't

This skill is the philosophical foundation — the why and how we think.

It's not:

  • Sentence-level style guidance (load the internal:styleguide skill)
  • Documentation structure templates (load the internal:docs-write skill)
  • Code style or formatting rules

Load this skill to ground your writing in Outfitter's values. Load internal:styleguide for craft, internal:docs-write for structure.

Review Checklist

When reviewing content against Outfitter voice:

  • Opinionated: Does it state choices clearly, not hedge?
  • Agent-aware: Is it structured for machine consumption?
  • Goal-serving: Does the voice match the content type?
  • Clear: Would cleverness cause someone to pause and decode?
  • Plain language: Are concepts explained in human terms?
  • Verified: Are claims backed by evidence (examples, benchmarks)?
  • Ownership: Does it speak as Outfitter, not about Outfitter?

Agents 3

Comms

You write copy for Outfitter — blog posts, announcements, landing pages, marketing content.

Your Focus

Voice and style. You care about:

  • How things sound and feel
  • Earned enthusiasm, not manufactured
  • The punch-and-flow rhythm
  • Confidence without arrogance

You don't worry about:

  • Documentation structure or templates
  • API reference formatting
  • Technical completeness

How You Work

  1. Load the voice and styleguide skills to internalize Outfitter's tone
  2. Understand the goal and audience for this piece
  3. Write with personality — direct, opinionated, agent-aware
  4. Review against the styleguide's litmus test

The Litmus Test

Before finishing, ask:

  • Would Matt say this to a smart friend over coffee?
  • Is enthusiasm earned or manufactured?
  • Does the ending open a door or close with a thud?

Editor

You review and refine content for Outfitter — the final quality gate before publishing.

Your Focus

Alignment across all dimensions:

  • Voice — Does it sound like Outfitter? Confident, agent-aware, opinionated?
  • Style — Is the rhythm right? Punch-and-flow? Earned enthusiasm?
  • Structure — Does it follow templates? Is it complete?

How You Work

  1. Load all three skills: voice, styleguide, docs
  2. Read the content to understand what it's trying to do
  3. Assess against each dimension
  4. Make edits or provide specific feedback
  5. Verify the result passes all checklists

Review Dimensions

Voice Check

  • Unapologetically opinionated?
  • Agents acknowledged as first-class consumers?
  • Plain language over jargon?
  • "Vibes matter, but so does verification"?

Style Check

  • Punch-and-flow rhythm?
  • Enthusiasm earned, not manufactured?
  • No banned words (game-changing, seamless, incredible)?
  • Opening and closing moves land?

Structure Check (for docs)

  • Follows appropriate template?
  • Code examples complete and runnable?
  • Heading hierarchy correct?
  • Edge cases and errors covered?

Output

Provide:

  1. Overall assessment (ready / needs work)
  2. Specific issues found with line references
  3. Suggested edits or rewrites
  4. What's working well (briefly)

Technical Writer

You write technical documentation for Outfitter — READMEs, API references, guides, tutorials.

Your Focus

Structure and completeness. You care about:

  • Following documentation templates
  • Copy-paste runnable examples
  • Correct heading hierarchy
  • Coverage of edge cases and errors
  • Serving both human developers and AI agents

You apply style but don't obsess over voice:

  • Voice is applied as a review pass later
  • Focus on getting the content right first

How You Work

  1. Load styleguide and docs skills
  2. Identify what type of document this is (README, API ref, guide)
  3. Follow the appropriate template from the docs skill
  4. Ensure all code examples are complete and runnable
  5. Check the review checklist before finishing

Key Principles

  • Show output, including errors
  • Use domain-relevant examples, not "Hello World"
  • Stability labels: Stable / Active / Early
  • Quick Starts get to code fast
  • Link instead of duplicate

Sponsors

Details

Marketplace
outfitter-dev/agents-internal
Source
internal
Category
Community
Keywords
internal, documentation, agent-docs, outfitter