
internal
Internal Outfitter development skills for documentation, agent setup, and project conventions
- version
- 0.4.2
Install
/plugin install internal@outfitter-internalRun it inside Claude Code after adding the marketplace with /plugin marketplace add outfitter-dev/agents-internal.
Contents
Discovered from sourceSkills 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
| Include | Exclude |
|---|---|
| Project structure overview | Tool-specific instructions |
| Key commands | Claude task management |
| Architectural patterns | Codex sandbox config |
| Development principles | MCP server setup |
| Code style conventions | IDE 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
| Include | Exclude |
|---|---|
| Task management patterns | Project architecture |
| Claude-specific tool preferences | Code style (goes in AGENTS.md) |
| MCP server usage | Testing approach |
| Subagent coordination | Git 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
| Directory | Purpose |
|---|---|
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
| Alias | Repo | Required Plugin |
|---|---|---|
outfitter | outfitter-dev/agents | outfitter@outfitter |
outfitter-internal | outfitter-dev/agents-internal | outfitter-dev@outfitter-internal |
Optional Plugins
From outfitter marketplace:
| Plugin | Purpose |
|---|---|
gt | Graphite stacked PR workflows |
but | GitButler virtual branch workflows |
cli-dev | CLI 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 Type | Example | Behavior |
|---|---|---|
| Section name | just the Quick Start | Audit only that section |
| Quality dimension | focus on correctness | Prioritize that checklist |
| Specific question | are 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)
| Check | How to Verify |
|---|---|
| Code examples run | Extract and execute each example. Report errors verbatim. |
| API signatures match | Compare documented signatures against source code. |
| Links resolve | Check each link target exists (relative paths, anchors, URLs). |
| Technical claims accurate | Cross-reference against implementation or authoritative source. |
| Versions current | Verify version numbers match package.json, Cargo.toml, etc. |
Completeness (nothing missing)
| Check | How to Verify |
|---|---|
| Required sections present | Compare against applicable template (README, API ref, guide). |
| Parameters documented | Each param has: type, purpose, constraints, default value. |
| Error scenarios covered | Document what happens when things go wrong. |
| Edge cases addressed | Empty inputs, nulls, boundaries, concurrent access. |
| Success and failure examples | Show both happy path and error handling. |
Comprehensiveness (depth)
| Check | How to Verify |
|---|---|
| Common use cases | List 3-5 typical scenarios; verify each is addressed. |
| Migration paths | Breaking changes include upgrade instructions. |
| Cross-references | Related docs linked where helpful. |
| Agent-friendly | Structured for AI consumption (clear headers, examples). |
| Troubleshooting | Common issues and solutions documented. |
Execution
- Identify target — What documentation is being checked?
- Run checks — Work through the checklist, executing verification steps
- Collect evidence — Note specific line numbers, error messages, missing items
- Classify issues — Blocking (must fix) vs. suggestions (nice to have)
- 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.
| Dimension | docs-review | docs-check |
|---|---|---|
| Focus | Voice, style, structure | Correctness, completeness |
| Question | "Does it sound right?" | "Is it accurate and complete?" |
| Approach | Subjective assessment | Objective verification |
| Output | Editorial feedback | Pass/fail with evidence |
| Speed | Quick pass | Thorough 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:styleguideskill for sentence rhythm, metaphors, structural moves - Load the
internal:voiceskill 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:
- Types — Self-documenting code through TypeScript types
- Inline comments — TSDoc/JSDoc for non-obvious decisions
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
| File | Purpose |
|---|---|
README.md | Entry point for humans — quick start, links to docs |
CONTRIBUTING.md | Contribution guidelines (if applicable) |
CHANGELOG.md | Version 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
| Directory | Content |
|---|---|
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/
| README | docs/ |
|---|---|
| Quick start (5-10 steps max) | Full tutorials |
| Feature list (bullet points) | Feature deep-dives |
| Installation options | Configuration reference |
| Links to detailed docs | The 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:
| Label | Meaning | Guidance |
|---|---|---|
| Stable | APIs locked, breaking changes rare | Safe to depend on |
| Active | APIs evolving based on usage | Watch for updates |
| Early | APIs will change, not production-ready | Use with caution |
Avoid metaphorical labels (Cold/Warm/Hot, etc.) — literal labels require no interpretation.
Quick Start Best Practices
-
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 -
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 requiredShowing error output proves your error handling works.
-
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. -
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
- Update with code: Documentation changes must accompany code changes
- Review regularly: Audit documentation quarterly for accuracy
- Remove outdated content: Delete obsolete information rather than marking as deprecated
- Version appropriately: Clearly document breaking changes and migration paths
- 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
| Metaphor | Use 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
| Type | Function | Example |
|---|---|---|
| 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:
- Would Matt say this to a smart friend over coffee?
- Is there a concrete example within two paragraphs of any claim?
- Does the ending open a door or close with a thud?
- Would a reader roll their eyes at any metaphor?
- 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 of | Use |
|---|---|
node file.ts or ts-node file.ts | bun file.ts |
jest or vitest | bun test |
webpack or esbuild (CLI) | bun build |
npm install / yarn / pnpm | bun install |
npm run script | bun run script |
npx package | bunx package |
nodemon | bun --watch |
node --env-file=.env | bun (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
- Check Bun docs first: https://bun.sh/docs
- Search for
Bun.orbun:in docs - Test if Node.js API you're using has faster Bun equivalent
- 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 API | Replaces |
|---|---|
bun:test | jest, vitest, mocha |
expect() | chai, expect.js |
import { describe, test, expect } from 'bun:test';
Database & Storage
| Bun API | Replaces |
|---|---|
bun:sqlite | better-sqlite3, sql.js |
Bun.sql | pg, postgres.js, mysql2 |
Bun.redis | ioredis, redis |
Bun.s3 | @aws-sdk/client-s3 |
import { Database } from 'bun:sqlite';
const client = Bun.redis();
const bucket = Bun.s3('my-bucket');
Networking
| Bun API | Replaces |
|---|---|
Bun.listen() | net.createServer |
Bun.connect() | net.connect |
Bun.udpSocket() | dgram.createSocket |
Bun.dns | dns.lookup |
HTTP
| Bun API | Replaces |
|---|---|
Bun.serve() | express, fastify, http |
Bun.fetch() | node-fetch, axios, got |
Bun.serve({ port: 3000, fetch: (req) => new Response('ok') });
Shell & Process
| Bun API | Replaces |
|---|---|
Bun.$ | execa, shelljs, zx |
Bun.spawn() | child_process.spawn |
Bun.spawnSync() | child_process.spawnSync |
import { $ } from 'bun';
await $`ls -la`;
File System
| Bun API | Replaces |
|---|---|
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 API | Replaces |
|---|---|
Bun.password.hash() | bcrypt, argon2 |
Bun.hash() | xxhash, murmur, crc32 |
Bun.CryptoHasher | crypto.createHash |
Bun.Glob | glob, fast-glob, minimatch |
Bun.semver | semver |
Bun.YAML.parse() | js-yaml, yaml |
Bun.TOML.parse() | toml |
Bun.gzipSync() | zlib, pako |
Bun.zstdCompressSync() | zstd-codec |
Bun.Archive | tar, archiver |
Bun.sleep() | delay, timers-promises |
Bun.deepEquals() | lodash.isEqual, deep-equal |
Bun.escapeHTML() | escape-html |
Bun.stringWidth() | string-width |
Bun.Cookie | cookie, 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 API | Replaces |
|---|---|
Bun.build() | esbuild, rollup, webpack |
bun build --compile | pkg, 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 strategiesoutfitter: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
| Principle | In Practice |
|---|---|
| Opinionated | State choices clearly. Explain why. Don't hedge. |
| Agent-first | Structure for machines. Runnable examples. Typed errors. |
| Goal-serving | Match voice to container. Quick starts are quick. |
| Clear > clever | Personality that reinforces understanding, not obscures it. |
| Plain language | Save generics for code. Use words people say. |
| Earned confidence | Claims backed by examples, benchmarks, tests. |
| Ownership stance | First-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 drophas personality without sacrificing meaning.crumb newis 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:styleguideskill) - Documentation structure templates (load the
internal:docs-writeskill) - 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
- Load the voice and styleguide skills to internalize Outfitter's tone
- Understand the goal and audience for this piece
- Write with personality — direct, opinionated, agent-aware
- 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
- Load all three skills: voice, styleguide, docs
- Read the content to understand what it's trying to do
- Assess against each dimension
- Make edits or provide specific feedback
- 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:
- Overall assessment (ready / needs work)
- Specific issues found with line references
- Suggested edits or rewrites
- 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
- Load styleguide and docs skills
- Identify what type of document this is (README, API ref, guide)
- Follow the appropriate template from the docs skill
- Ensure all code examples are complete and runnable
- 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