---
name: blockrun
description: "BlockRun works with Claude Code and Google Antigravity."
risk: critical
source: community
date_added: "2026-02-27"
---

# BlockRun

**BlockRun works with Claude Code and Google Antigravity.**

You can't generate images. You have no real-time X/Twitter access. BlockRun gives you these capabilities.

## Philosophy

You have a wallet. When you need a capability you lack, you pay for it autonomously.

| You Need | You Call | Pricing |
|----------|----------|---------|
| Image generation | DALL-E | $0.04/image |
| Real-time X data | Grok + Live Search | $0.025/source |
| Second opinion | GPT-5.2 | $1.75/M input, $14/M output |
| Cheaper processing | DeepSeek | $0.14/M input, $0.28/M output |

**How it works:** BlockRun uses x402 micropayments to route your requests to OpenAI, xAI, Google, and other providers. No API keys needed - your wallet pays per token.

## Budget Control (Optional)

If the user specifies a budget (e.g., "use at most $1"), track spending and stop when budget is reached:

```python
from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()
budget = 1.0  # User's budget

# Before each call, check if within budget
spending = client.get_spending()
if spending['total_usd'] >= budget:
    print(f"Budget reached: ${spending['total_usd']:.4f} spent")
    # Stop making calls
else:
    response = client.chat("openai/gpt-5.2", "Hello!")

# At the end, report spending
spending = client.get_spending()
print(f"💰 Total spent: ${spending['total_usd']:.4f} across {spending['calls']} calls")
```

## When to Use
| Trigger | Your Action |
|---------|-------------|
| User explicitly requests ("blockrun second opinion with GPT on...", "use grok to check...", "generate image with dall-e") | Execute via BlockRun |
| User needs something you can't do (images, live X data) | Suggest BlockRun, wait for confirmation |
| You can handle the task fine | Do it yourself, don't mention BlockRun |

## Example User Prompts

Users will say things like:

| User Says | What You Do |
|-----------|-------------|
| "blockrun generate an image of a sunset" | Call DALL-E via ImageClient |
| "use grok to check what's trending on X" | Call Grok with `search=True` |
| "blockrun GPT review this code" | Call GPT-5.2 via LLMClient |
| "what's the latest news about AI agents?" | Suggest Grok (you lack real-time data) |
| "generate a logo for my startup" | Suggest DALL-E (you can't generate images) |
| "blockrun check my balance" | Show wallet balance via `get_balance()` |
| "blockrun deepseek summarize this file" | Call DeepSeek for cost savings |

## Wallet & Balance

Use `setup_agent_wallet()` to auto-create a wallet and get a client. This shows the QR code and welcome message on first use.

**Initialize client (always start with this):**
```python
from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()  # Auto-creates wallet, shows QR if new
```

**Check balance (when user asks "show balance", "check wallet", etc.):**
```python
balance = client.get_balance()  # On-chain USDC balance
print(f"Balance: ${balance:.2f} USDC")
print(f"Wallet: {client.get_wallet_address()}")
```

**Show QR code for funding:**
```python
from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address

# ASCII QR for terminal display
print(generate_wallet_qr_ascii(get_wallet_address()))
```

## SDK Usage

**Prerequisite:** Install the SDK with `pip install blockrun-llm`

### Basic Chat
```python
from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()  # Auto-creates wallet if needed
response = client.chat("openai/gpt-5.2", "What is 2+2?")
print(response)

# Check spending
spending = client.get_spending()
print(f"Spent ${spending['total_usd']:.4f}")
```

### Real-time X/Twitter Search (xAI Live Search)

**IMPORTANT:** For real-time X/Twitter data, you MUST enable Live Search with `search=True` or `search_parameters`.

```python
from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()

# Simple: Enable live search with search=True
response = client.chat(
    "xai/grok-3",
    "What are the latest posts from @blockrunai on X?",
    search=True  # Enables real-time X/Twitter search
)
print(response)
```

### Advanced X Search with Filters

```python
from blockrun_llm import setup_agent_wallet

client = setup_agent_wallet()

response = client.chat(
    "xai/grok-3",
    "Analyze @blockrunai's recent content and engagement",
    search_parameters={
        "mode": "on",
        "sources": [
            {
                "type": "x",
                "included_x_handles": ["blockrunai"],
                "post_favorite_count": 5
            }
        ],
        "max_search_results": 20,
        "return_citations": True
    }
)
print(response)
```

### Image Generation
```python
from blockrun_llm import ImageClient

client = ImageClient()
result = client.generate("A cute cat wearing a space helmet")
print(result.data[0].url)
```

## xAI Live Search Reference

Live Search is xAI's real-time data API. Cost: **$0.025 per source** (default 10 sources = ~$0.26).

To reduce costs, set `max_search_results` to a lower value:
```python
# Only use 5 sources (~$0.13)
response = client.chat("xai/grok-3", "What's trending?",
    search_parameters={"mode": "on", "max_search_results": 5})
```

### Search Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `mode` | string | "auto" | "off", "auto", or "on" |
| `sources` | array | web,news,x | Data sources to query |
| `return_citations` | bool | true | Include source URLs |
| `from_date` | string | - | Start date (YYYY-MM-DD) |
| `to_date` | string | - | End date (YYYY-MM-DD) |
| `max_search_results` | int | 10 | Max sources to return (customize to control cost) |

### Source Types

**X/Twitter Source:**
```python
{
    "type": "x",
    "included_x_handles": ["handle1", "handle2"],  # Max 10
    "excluded_x_handles": ["spam_account"],        # Max 10
    "post_favorite_count": 100,  # Min likes threshold
    "post_view_count": 1000      # Min views threshold
}
```

**Web Source:**
```python
{
    "type": "web",
    "country": "US",  # ISO alpha-2 code
    "allowed_websites": ["example.com"],  # Max 5
    "safe_search": True
}
```

**News Source:**
```python
{
    "type": "news",
    "country": "US",
    "excluded_websites": ["tabloid.com"]  # Max 5
}
```

## Available Models

| Model | Best For | Pricing |
|-------|----------|---------|
| `openai/gpt-5.2` | Second opinions, code review, general | $1.75/M in, $14/M out |
| `openai/gpt-5-mini` | Cost-optimized reasoning | $0.30/M in, $1.20/M out |
| `openai/o4-mini` | Latest efficient reasoning | $1.10/M in, $4.40/M out |
| `openai/o3` | Advanced reasoning, complex problems | $10/M in, $40/M out |
| `xai/grok-3` | Real-time X/Twitter data | $3/M + $0.025/source |
| `deepseek/deepseek-chat` | Simple tasks, bulk processing | $0.14/M in, $0.28/M out |
| `google/gemini-2.5-flash` | Very long documents, fast | $0.15/M in, $0.60/M out |
| `openai/dall-e-3` | Photorealistic images | $0.04/image |
| `google/nano-banana` | Fast, artistic images | $0.01/image |

*M = million tokens. Actual cost depends on your prompt and response length.*

## Cost Reference

All LLM costs are per million tokens (M = 1,000,000 tokens).

| Model | Input | Output |
|-------|-------|--------|
| GPT-5.2 | $1.75/M | $14.00/M |
| GPT-5-mini | $0.30/M | $1.20/M |
| Grok-3 (no search) | $3.00/M | $15.00/M |
| DeepSeek | $0.14/M | $0.28/M |

| Fixed Cost Actions | |
|-------|--------|
| Grok Live Search | $0.025/source (default 10 = $0.25) |
| DALL-E image | $0.04/image |
| Nano Banana image | $0.01/image |

**Typical costs:** A 500-word prompt (~750 tokens) to GPT-5.2 costs ~$0.001 input. A 1000-word response (~1500 tokens) costs ~$0.02 output.

## Setup & Funding

**Wallet location:** `$HOME/.blockrun/.session` (e.g., `/Users/username/.blockrun/.session`)

**First-time setup:**
1. Wallet auto-creates when `setup_agent_wallet()` is called
2. Check wallet and balance:
```python
from blockrun_llm import setup_agent_wallet
client = setup_agent_wallet()
print(f"Wallet: {client.get_wallet_address()}")
print(f"Balance: ${client.get_balance():.2f} USDC")
```
3. Fund wallet with $1-5 USDC on Base network

**Show QR code for funding (ASCII for terminal):**
```python
from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address
print(generate_wallet_qr_ascii(get_wallet_address()))
```

## Troubleshooting

**"Grok says it has no real-time access"**
→ You forgot to enable Live Search. Add `search=True`:
```python
response = client.chat("xai/grok-3", "What's trending?", search=True)
```

**Module not found**
→ Install the SDK: `pip install blockrun-llm`

## Updates

```bash
pip install --upgrade blockrun-llm
```

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: blog-writing-guide
description: "This skill enforces Sentry's blog writing standards across every post — whether you're helping an engineer write their first blog post or a marketer draft a product announcement."
risk: critical
source: community
date_added: '2026-03-06'
---

# Sentry Blog Writing Skill

This skill enforces Sentry's blog writing standards across every post — whether you're helping an engineer write their first blog post or a marketer draft a product announcement.

**The bar:** Every Sentry blog post should be something a senior engineer would share in their team's Slack, or reference in a technical decision.

What follows are the core principles to internalize and apply to every piece of content.

## When to Use
- You need to draft or edit a Sentry blog post.
- The task involves technical storytelling, product announcements, or engineering deep-dives in Sentry's blog voice.
- You want blog content that is opinionated, specific, and technically credible rather than generic marketing copy.

## The Sentry Voice

**We sound like:** A senior developer at a conference afterparty explaining something they're genuinely excited about — smart, specific, a little irreverent, deeply knowledgeable.

**We don't sound like:** A corporate blog, a press release, a sales deck, or an AI-generated summary.

Be technically precise, opinionated, and direct. Humor is welcome but should serve the content, not replace it. Sarcasm works. One good joke per post is plenty.

Use "we" (Sentry) and "you" (the reader). This is a conversation, not a paper.

## Banned Language

Never use these. They are automatic red flags:

- "We're excited/thrilled to announce" — just announce it
- "Best-in-class" / "industry-leading" / "cutting-edge" — show, don't tell
- "Seamless" / "seamlessly" — nothing is seamless
- "Empower" / "leverage" / "unlock" — say what you actually mean
- "Robust" — describe what makes it robust instead
- "At [Company], we believe..." — just state the belief
- "Streamline" — everyone is streamlining, stop
- Filler transitions: "That being said," "It's worth noting that," "At the end of the day," "Without further ado," "As you might know"
- "In this blog post, we will explore..." — be direct, just start

## The Opening (First 2-3 Sentences)

The opening must do one of two things: **state the problem** or **state the conclusion**. Never start with background, company history, or hype.

**Good:** "Two weeks before launch, we killed our entire metrics product. Here's why pre-aggregating time-series metrics breaks down for debugging, and how we rebuilt the system from scratch."

**Bad:** "At Sentry, we're always looking for ways to improve the developer experience. Today, we're thrilled to share some exciting updates to our metrics product that we think you'll love."

## Structure: Follow the Reader's Questions

Structure every post around what the reader is actually wondering, not your internal narrative:

1. **What problem does this solve?** (1-2 paragraphs max)
2. **How does it actually work?** Not buttons-you-click, but underlying technology. (Bulk of the post — be specific)
3. **What were the trade-offs or alternatives?** (This separates good from great)
4. **How do I use/try/implement this?** (Concrete next steps)

For engineering deep-dives, also address:
5. **What did we try that didn't work?** (Builds trust)
6. **What are the known limitations?** (Shows intellectual honesty)

## Section Headings Must Convey Information

**Weak:** "Background," "Architecture," "Results," "Conclusion"

**Strong:** "Why time-series pre-aggregation destroys debugging context," "The scatter-gather approach to distributed GROUP BY," "Where this breaks down: the cardinality wall"

## Technical Quality Standards

**Numbers over adjectives.** If you make a performance claim, include the number.
- Bad: "This significantly reduced our error processing time."
- Good: "This reduced our p99 error processing time from 340ms to 45ms — a 7.5× improvement."

**Code must work.** If a post includes code, test it. Include imports, configuration, and context. Comments should explain *why*, not *what*.

**Diagrams for systems.** If you describe a system with more than two interacting components, include a diagram. Label with real service names, not generic boxes.

**Honesty over hype.** Never overstate what a feature does. Acknowledge limitations. If something is in beta, say so. If a competitor does something well, it's okay to note that. Do not claim AI features are more capable than they are — "Seer suggests a likely root cause" ≠ "Seer finds the root cause."

## Title Guidelines

The title is the highest-leverage sentence in the post. It must stop a developer scrolling through their RSS feed or Twitter.

**Strong titles** make a specific claim, tell a story, or promise a specific payoff:
- "The metrics product we built worked. But we killed it and started over anyway"
- "How we reduced release delays by 5% by fixing Salt"
- "Your JavaScript bundle has 47% dead code. Here's how to find it."

**Weak titles** are vague announcements:
- "Introducing our new metrics product"
- "Performance improvements in Sentry"
- "AI-powered debugging with Seer"

## The Closing

End with something useful — a link to docs, a way to try it, a call to give feedback. Never end with generic hype ("We can't wait to see what you build!") or recaps of what you just said.

## Post Types

Here's the quick map by post type:

| Type | Goal | Byline |
|------|------|--------|
| Engineering Deep Dive | Explain a technical system/decision so other engineers learn | The engineer(s) who built it. Always. |
| Product Launch | Explain what shipped, why it matters, how to use it | PM, engineer, or DevEx. Not PMM unless marketing built it. |
| Postmortem | Transparent failure analysis with timeline and fixes | Engineering leadership |
| Data / Research | Original insights from Sentry's unique data position | Data team, engineering, or research |
| Tutorial / Guide | Help a developer accomplish something specific | DevEx, engineer, or community contributor |

## The "Would I Share This?" Test

Before publishing, ask: Would a developer share this post? Does it have a shot at getting on Hacker News? If the answer is no, the post either needs more depth, more original insight, or it belongs in the changelog instead.

Posts worth sharing contain at least one of:
- A technical decision explained with trade-offs
- Original data or research not found elsewhere
- A real-world debugging story with specific details
- An honest accounting of something that went wrong
- A how-to that saves the reader real time

## Non-Negotiables (Quick Reference)

1. Never publish without a real person's name on it. No "The Sentry Team" bylines.
2. Never publish code that doesn't work.
3. Never say "we're excited to announce." Just announce it.
4. If you describe a system, include a diagram.
5. If you make a performance claim, include the number.
6. If you discuss a decision, explain what you didn't choose and why.
7. Every post must have a clear "who is this for" in the author's mind before writing.
8. Changelogs belong in the changelog. Blog posts should offer something more.
9. When in doubt, go deeper. The risk of being too shallow is far greater than being too detailed.
10. Write the post you wish existed when you were trying to solve this problem.

## When Reviewing or Editing a Draft

Run through both checklists:

**Technical Review:**
- All technical claims accurate
- Code samples work
- Architecture descriptions match reality
- Numbers and benchmarks correct
- No oversimplifications that would make an expert cringe

**Editorial Review:**
- Opening hooks reader within 2 sentences
- Passes the "would I share this?" test
- No corporate language, filler, or fluff
- Headings convey information
- Right length (not padded, not too thin)
- Title is specific and compelling

**Final Check:**
- Author byline is correct (real person's name)
- Links to docs/getting-started included
- Post doesn't duplicate what's in the changelog

When providing feedback, be specific and constructive. Quote the weak passage, explain why it's weak, and rewrite it to show the standard.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: blueprint
description: "Turn a one-line objective into a step-by-step construction plan any coding agent can execute cold. Each step has a self-contained context brief — a fresh agent in a new session can pick up any step without reading prior steps."
category: planning
risk: critical
source: community
date_added: "2026-03-10"
---

# Blueprint — Construction Plan Generator

Turn a one-line objective into a step-by-step plan any coding agent can execute cold.

## Overview

Blueprint is for multi-session, multi-agent engineering projects where each step must be independently executable by a fresh agent that has never seen the conversation history. Install it once, invoke it with `/blueprint <project> <objective>`.

## When to Use This Skill

- Use when the task requires multiple PRs or sessions
- Use when multiple agents or team members need to share execution
- Use when you want adversarial review of the plan before execution
- Use when parallel step detection and dependency graphs matter

## How It Works

1. **Research** — Scans the codebase, reads project memory, runs pre-flight checks
2. **Design** — Breaks the objective into one-PR-sized steps, identifies parallelism, assigns model tiers
3. **Draft** — Generates the plan from a structured template with branch workflow rules, CI policy, and rollback strategies inline
4. **Review** — Delegates adversarial review to a strongest-model sub-agent (falls back to default model if unavailable)
5. **Register** — Saves the plan and updates project memory

## Examples

### Example 1: Database migration
```
/blueprint myapp "migrate database to PostgreSQL"
```

### Example 2: Plugin extraction
```
/blueprint antbot "extract providers into plugins"
```

## Best Practices

- ✅ Use for tasks requiring 3+ PRs or multiple sessions
- ✅ Let Blueprint auto-detect git/gh availability — it degrades gracefully
- ❌ Don't invoke for tasks completable in a single PR
- ❌ Don't invoke when the user says "just do it"

## Key Differentiators

- **Cold-start execution**: Every step has a self-contained context brief
- **Adversarial review gate**: Strongest-model review before execution
- **Markdown-first distribution**: The reviewed revision is primarily instructions and templates, but installing or following it can still cause an agent to run commands. Treat the repository as untrusted until inspected.
- **Plan mutation protocol**: Steps can be split, inserted, skipped with audit trail

## Installation

Do not clone a moving branch directly into an active skills directory. First ask
the user to approve network access to the named repository. Then inspect the
reviewed revision and ask separately before activating it:

```bash
review_dir="$(mktemp -d)"
git clone --filter=blob:none https://github.com/antbotlab/blueprint.git "$review_dir/blueprint"
git -C "$review_dir/blueprint" checkout --detach 07c5b305cf2d95d584a0d0398c390e839fec5954
git -C "$review_dir/blueprint" ls-files
git -C "$review_dir/blueprint" status --short
```

Read `SKILL.md` and every bundled file at that exact commit. Check for scripts,
hooks, symlinks, network calls, credential access, and instructions that request
commands or elevated permissions. Only after explicit user approval, copy the
reviewed files into the selected host's skills directory. Re-review a newer
revision instead of silently updating this pin.

## Additional Resources

- [GitHub Repository](https://github.com/antbotlab/blueprint)
- [Examples: small plan](https://github.com/antbotlab/blueprint/blob/main/examples/small-plan.md)
- [Examples: large plan](https://github.com/antbotlab/blueprint/blob/main/examples/large-plan.md)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
- A pinned revision is reproducible, not automatically trustworthy; its contents still require review.


---
name: boost-asio-pro
description: "Use when writing asynchronous C++ networking code with Boost.Asio or standalone Asio — TCP/UDP servers and clients, SSL/TLS, timers, strands, composed async ops. Covers io_context, co_spawn, awaitable, async_read/async_write, asio::spawn, yield_context, and pre-C++20 callback styles."
category: development
risk: safe
source: community
source_repo: alexprivalov/boost-asio-skill
source_type: community
date_added: "2026-08-18"
author: alexprivalov
tags: [cpp, boost, asio, async, networking, coroutines]
tools: [claude, cursor, gemini]
license: "MIT"
license_source: "https://github.com/alexprivalov/boost-asio-skill/blob/main/LICENSE"
---

# Boost.Asio / standalone Asio

## Overview

Write async C++ networking code that compiles on the *user's* Boost, not the newest one. Asio's API changed shape three times (classic `io_service` → `io_context` → C++20 coroutines) and most Asio code on the internet is from the first era, so **pick the style from the toolchain first**, then follow that style's reference file.

**References:** [Boost.Asio](https://www.boost.org/doc/libs/latest/doc/html/boost_asio.html) · [standalone Asio](https://think-async.com/Asio/)

Asio's API changed shape three times, so the same task has three correct answers depending on the Boost version in front of you. This skill makes the agent establish that version first, then apply the rules that are genuinely easy to get wrong — strand versus write serialization, buffer and connection lifetime, composed reads for framing — and finally check its own output against a list before calling it done.

## When to Use This Skill

- Use when writing or reviewing async C++ networking code with Boost.Asio or standalone Asio: TCP/UDP servers and clients, SSL/TLS streams, timers, resolvers.
- Use when the code involves `io_context`, `io_service`, `co_spawn`, `awaitable`, `async_read`, `async_write`, `strand`, `asio::spawn`, `yield_context`, or completion-handler callbacks.
- Use when the target toolchain is old: an older Boost or a pre-C++20 standard, where coroutine examples will not compile.
- Use when async code compiles but misbehaves: interleaved writes, dangling buffers, sockets closing early, `operation_aborted` treated as an error.

## Step 1: pick the style (do this before writing code)

Determine the Boost (or Asio) version and the C++ standard actually in use — `find_package(Boost)` output, `dpkg -l libboost-dev`, `brew info boost`, `CMAKE_CXX_STANDARD`, or ask. Do not assume the newest.

| Boost | C++ std | Style | Read |
|-------|---------|-------|------|
| ≥ 1.77 | C++20 | Coroutines (`co_await` + `awaitable<T>`) — preferred | [references/coroutines.md](references/coroutines.md) |
| ≥ 1.74 | C++11–17 | Completion handlers (callbacks) — the portable baseline | [references/pre-cpp20.md](references/pre-cpp20.md) |
| ≥ 1.80 | C++11–17 | Stackful `asio::spawn` + `yield_context` (links Boost.Coroutine — not header-only) | [references/pre-cpp20.md](references/pre-cpp20.md) |
| 1.62–1.65 | C++11 | Classic `io_service` / `strand.wrap` / `expires_from_now` | [references/classic-boost.md](references/classic-boost.md) |

SSL/TLS in any style: [references/ssl.md](references/ssl.md). CMake for any style: [references/build.md](references/build.md).

`io_context`, `make_strand`, `bind_executor`, `steady_timer`, `signal_set`, `async_read`/`async_write`/`async_read_until`, buffers and `resolver` are **library** features — identical in the coroutine and callback styles. Only the suspension mechanism differs.

## Step 2: version floors (verified by compiling, not from docs)

Reach for one of these and the build breaks on older distros:

| Feature | Floor |
|---------|-------|
| `experimental/awaitable_operators.hpp` (the `\|\|` / `&&` operators) | **Boost ≥ 1.77** / Asio ≥ 1.20 |
| `as_tuple` completion token | **Boost ≥ 1.79** / Asio ≥ 1.21 |
| `co_composed` (custom composed ops) | **Boost ≥ 1.85** / Asio ≥ 1.30 |
| 3-arg `asio::spawn(ex, fn, token)` | **Boost ≥ 1.80** (older Boost has only `spawn(ex, fn)`) |
| `any_io_executor` (`strand<any_io_executor>`, `tcp::socket`'s default executor) | **Boost ≥ 1.74** — the floor for the callback style; below it, use legacy `io_context::strand` |
| `io_context`, `make_strand`, `expires_after` | **Boost ≥ 1.66** — below it, classic `io_service` |

Distro floors that bite: **Debian bookworm ships Boost 1.74** (no `awaitable_operators.hpp` — `#include` fails outright), Ubuntu 20.04 ships 1.71 (no `any_io_executor`), Debian 9 ships 1.62.

Language, not library: the chrono literals `250ms` / `30s` are **C++14**. For a true C++11 build write `std::chrono::milliseconds(250)`.

## Step 3: the rules that are actually easy to get wrong

**A strand does not serialize writes.** A strand serializes handler *execution*, not whole composed operations. Two `async_write`s in flight on the same strand still **interleave bytes on the wire**. Full-duplex (a read loop plus concurrent pushes/replies) needs a per-connection strand **and** an outbound queue with an in-flight flag, so at most one `async_write` exists at a time. This is the single most common wrong answer about Asio.

**Buffers do not own memory.** `asio::buffer()` is a view. Storage must outlive the operation: coroutine locals are fine across `co_await` in the same frame; in callback style the same data must become a **member**, not a local.

**Connections must outlive their handlers.** `enable_shared_from_this`, and capture `self` in *every* `co_spawn` / handler — read loop, write loop, and each timer.

**Frame with composed reads.** `async_read` (fills the buffer exactly) for a length prefix and then the body; never `async_read_some`, which returns short.

**Wrap `as_tuple`.** Always `as_tuple(use_awaitable)`. Bare `as_tuple` resolves against the operation's default token and compiles in some contexts, fails in others.

**`async_accept(make_strand(...))` changes two things**: it forces an explicit completion token back on the call, and the accepted socket is `basic_stream_socket<tcp, strand<...>>`, not `tcp::socket`. Take it **by value** or with `auto` — binding it to `tcp::socket&` will not compile.

**Re-arming a timer resolves the pending wait with `operation_aborted`.** In an idle-timeout loop that is the signal to keep waiting, not an error.

**GCC needs `-fcoroutines`** for the C++20 style, and header-only Boost needs `BOOST_ERROR_CODE_HEADER_ONLY` defined in exactly one place (CMake).

## Common mistakes

| Mistake | Fix |
|---------|-----|
| Buffer dangling (local goes out of scope during async op) | Ensure buffer lifetime ≥ operation lifetime; coroutine locals or members, not callback locals |
| Forgetting `io.run()` | No handlers dispatch without `run()` / `run_one()` |
| Concurrent socket access without strand | Wrap in `strand<>` or serialize via one coroutine chain |
| Assuming a strand prevents interleaved writes | Add a write queue — see Step 3 |
| Using `use_awaitable` where `deferred` suffices | Omit the token (default is `deferred`) unless using `\|\|` / `&&` |
| Ignoring short reads/writes | Use composed `async_read` / `async_write` / `async_read_until`, not `async_read_some` |
| Not setting `reuse_address` on the acceptor | Set before `bind`/`listen` or restarts hit "address in use" |
| SSL operations without a strand | *All* `ssl::stream` ops need strand synchronization |
| Blocking inside a handler | Never block in a completion handler |
| Accepting a socket with the wrong executor type | See `async_accept(make_strand(...))` in Step 3 |
| Requiring the `Boost::system` component | Header-only since 1.74: `Boost::headers` + `BOOST_ERROR_CODE_HEADER_ONLY`. Only classic (pre-1.66) needs the link |
| Missing `-fcoroutines` on GCC | Build fails — add `$<$<CXX_COMPILER_ID:GNU>:-fcoroutines>` |
| Writing coroutine code for a Boost that predates it | Do Step 1 first |

## Boost.Asio vs standalone Asio

Same author, same API — namespace and includes differ.

| Aspect | Boost.Asio | Standalone Asio |
|--------|-----------|-----------------|
| Namespace / include | `boost::asio` / `<boost/asio.hpp>` | `asio` / `<asio.hpp>` |
| Error code | `boost::system::error_code` | `asio::error_code` (or `std::error_code`) |
| Install (brew) | `brew install boost` | `brew install asio` |
| CMake | `Boost::headers` | manual include path |
| Version (2025) | 1.87–1.90 (with Boost) | 1.30–1.36 (independent) |
| Macro prefix | `BOOST_ASIO_` | `ASIO_` |

Support both with a shim, then use `net::` throughout:
```cpp
#ifdef USE_STANDALONE_ASIO
  #include <asio.hpp>
  namespace net = asio;
  using error_code = asio::error_code;
#else
  #include <boost/asio.hpp>
  namespace net = boost::asio;
  using error_code = boost::system::error_code;
#endif
namespace ssl = net::ssl;
using tcp = net::ip::tcp;
```

## Before you call it done

Check the code you just wrote against this list:

- [ ] Style matches the target Boost version and C++ standard (Step 1), and every API used clears its floor (Step 2).
- [ ] Every buffer passed to an async op outlives that op — no callback locals, no dangling `string_view`.
- [ ] At most one `async_write` per socket in flight, enforced by a queue + flag, if anything writes concurrently with reading.
- [ ] Every async chain on a shared object runs on the same strand; `self` captured in every handler and `co_spawn`.
- [ ] Framing / delimited reads use composed `async_read` / `async_read_until`.
- [ ] Errors are handled, not swallowed: `as_tuple(use_awaitable)` destructured, or the callback's `ec` checked, on every op.
- [ ] `operation_aborted` distinguished from real errors wherever a timer is re-armed or an op is cancelled.
- [ ] Acceptor sets `reuse_address`; shutdown path closes the acceptor and drains sessions.
- [ ] CMake has the standard, `-fcoroutines` for GCC (C++20 only), `BOOST_ERROR_CODE_HEADER_ONLY` in one place, and `Boost::coroutine` only if using stackful `spawn`.
- [ ] It compiles. Build it — most of the mistakes above are compile-time, and the version floors are only real once tested.

## Worked examples

Three CI-verified implementations of the same full-duplex framed-protocol server, one per style — copy from the one matching Step 1. Paths are relative to this skill directory; if only the skill was installed, they are at https://github.com/alexprivalov/boost-asio-skill/tree/main/examples.

- `../../examples/market-data-feed/` — C++20 coroutines (Boost 1.77+; verified 1.83–1.90)
- `../../examples/market-data-feed-precpp20/` — callbacks, C++11-clean (verified Boost 1.74+, incl. Windows/MSVC)
- `../../examples/market-data-feed-classic/` — classic `io_service` (verified back to Boost 1.62 / Debian 9)

## Official documentation

- Overview: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/overview.html
- Reference: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/reference.html
- Examples: https://www.boost.org/doc/libs/latest/doc/html/boost_asio/examples.html

## Limitations

- This skill does not replace compiling and testing against the target toolchain. The version floors it documents are only real once built — build the code.
- It does not cover Boost.Beast (HTTP/WebSocket), io_uring backends, or UDP multicast specifics.
- Stop and ask when the Boost version and C++ standard cannot be determined; the style choice depends on them.

## Security & Safety Notes

- Read-only guidance: this skill contains no shell commands, network fetches, credentials, or mutation instructions. The commands it names (`dpkg -l libboost-dev`, `brew info boost`) are local version queries.
- Networking code it produces accepts untrusted input. Validate length prefixes before allocating (`std::string body(n, 0)` with an attacker-controlled `n` is a memory-exhaustion vector — cap it), and verify peer certificates when using TLS rather than disabling verification to make a handshake pass.

## Related Skills

- `@cpp-pro` — general modern C++ idioms; this skill assumes them and adds the Asio-specific rules.


---
name: box-automation
description: "Automate Box operations including file upload/download, content search, folder management, collaboration, metadata queries, and sign requests through Composio's Box toolkit."
risk: critical
source: community
date_added: "2026-02-27"
---

# Box Automation via Rube MCP

Automate Box operations including file upload/download, content search, folder management, collaboration, metadata queries, and sign requests through Composio's Box toolkit.

## Prerequisites

- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Box connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `box`
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas

## Setup

**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `box`
3. If connection is not ACTIVE, follow the returned auth link to complete Box OAuth
4. Confirm connection status shows ACTIVE before running any workflows

## Core Workflows

### 1. Upload and Download Files

**When to use**: User wants to upload files to Box or download files from it

**Tool sequence**:
1. `BOX_SEARCH_FOR_CONTENT` - Find the target folder if path is unknown [Prerequisite]
2. `BOX_GET_FOLDER_INFORMATION` - Verify folder exists and get folder_id [Prerequisite]
3. `BOX_LIST_ITEMS_IN_FOLDER` - Browse folder contents and discover file IDs [Optional]
4. `BOX_UPLOAD_FILE` - Upload a file to a specific folder [Required for upload]
5. `BOX_DOWNLOAD_FILE` - Download a file by file_id [Required for download]
6. `BOX_CREATE_ZIP_DOWNLOAD` - Bundle multiple files/folders into a zip [Optional]

**Key parameters**:
- `parent_id`: Folder ID for upload destination (use `"0"` for root folder)
- `file`: FileUploadable object with `s3key`, `mimetype`, and `name` for uploads
- `file_id`: Unique file identifier for downloads
- `version`: Optional file version ID for downloading specific versions
- `fields`: Comma-separated list of attributes to return

**Pitfalls**:
- Uploading to a folder with existing filenames can trigger conflict behavior; decide overwrite vs rename semantics
- Files over 50MB should use chunk upload APIs (not available via standard tools)
- The `attributes` part of upload must come before the `file` part or you get HTTP 400 with `metadata_after_file_contents`
- File IDs and folder IDs are numeric strings extractable from Box web app URLs (e.g., `https://*.app.box.com/files/123` gives file_id `"123"`)

### 2. Search and Browse Content

**When to use**: User wants to find files, folders, or web links by name, content, or metadata

**Tool sequence**:
1. `BOX_SEARCH_FOR_CONTENT` - Full-text search across files, folders, and web links [Required]
2. `BOX_LIST_ITEMS_IN_FOLDER` - Browse contents of a specific folder [Optional]
3. `BOX_GET_FILE_INFORMATION` - Get detailed metadata for a specific file [Optional]
4. `BOX_GET_FOLDER_INFORMATION` - Get detailed metadata for a specific folder [Optional]
5. `BOX_QUERY_FILES_FOLDERS_BY_METADATA` - Search by metadata template values [Optional]
6. `BOX_LIST_RECENTLY_ACCESSED_ITEMS` - List recently accessed items [Optional]

**Key parameters**:
- `query`: Search string supporting operators (`""` exact match, `AND`, `OR`, `NOT` - uppercase only)
- `type`: Filter by `"file"`, `"folder"`, or `"web_link"`
- `ancestor_folder_ids`: Limit search to specific folders (comma-separated IDs)
- `file_extensions`: Filter by file type (comma-separated, no dots)
- `content_types`: Search in `"name"`, `"description"`, `"file_content"`, `"comments"`, `"tags"`
- `created_at_range` / `updated_at_range`: Date filters as comma-separated RFC3339 timestamps
- `limit`: Results per page (default 30)
- `offset`: Pagination offset (max 10000)
- `folder_id`: For `LIST_ITEMS_IN_FOLDER` (use `"0"` for root)

**Pitfalls**:
- Queries with offset > 10000 are rejected with HTTP 400
- `BOX_SEARCH_FOR_CONTENT` requires either `query` or `mdfilters` parameter
- Misconfigured filters can silently omit expected items; validate with small test queries first
- Boolean operators (`AND`, `OR`, `NOT`) must be uppercase
- `BOX_LIST_ITEMS_IN_FOLDER` requires pagination via `marker` or `offset`/`usemarker`; partial listings are common
- Standard folders sort items by type first (folders before files before web links)

### 3. Manage Folders

**When to use**: User wants to create, update, move, copy, or delete folders

**Tool sequence**:
1. `BOX_GET_FOLDER_INFORMATION` - Verify folder exists and check permissions [Prerequisite]
2. `BOX_CREATE_FOLDER` - Create a new folder [Required for create]
3. `BOX_UPDATE_FOLDER` - Rename, move, or update folder settings [Required for update]
4. `BOX_COPY_FOLDER` - Copy a folder to a new location [Optional]
5. `BOX_DELETE_FOLDER` - Move folder to trash [Required for delete]
6. `BOX_PERMANENTLY_REMOVE_FOLDER` - Permanently delete a trashed folder [Optional]

**Key parameters**:
- `name`: Folder name (no `/`, `\`, trailing spaces, or `.`/`..`)
- `parent__id`: Parent folder ID (use `"0"` for root)
- `folder_id`: Target folder ID for operations
- `parent.id`: Destination folder ID for moves via `BOX_UPDATE_FOLDER`
- `recursive`: Set `true` to delete non-empty folders
- `shared_link`: Object with `access`, `password`, `permissions` for creating shared links on folders
- `description`, `tags`: Optional metadata fields

**Pitfalls**:
- `BOX_DELETE_FOLDER` moves to trash by default; use `BOX_PERMANENTLY_REMOVE_FOLDER` for permanent deletion
- Non-empty folders require `recursive: true` for deletion
- Root folder (ID `"0"`) cannot be copied or deleted
- Folder names cannot contain `/`, `\`, non-printable ASCII, or trailing spaces
- Moving folders requires setting `parent.id` via `BOX_UPDATE_FOLDER`

### 4. Share Files and Manage Collaborations

**When to use**: User wants to share files, manage access, or handle collaborations

**Tool sequence**:
1. `BOX_GET_FILE_INFORMATION` - Get file details and current sharing status [Prerequisite]
2. `BOX_LIST_FILE_COLLABORATIONS` - List who has access to a file [Required]
3. `BOX_UPDATE_COLLABORATION` - Change access level or accept/reject invitations [Required]
4. `BOX_GET_COLLABORATION` - Get details of a specific collaboration [Optional]
5. `BOX_UPDATE_FILE` - Create shared links, lock files, or update permissions [Optional]
6. `BOX_UPDATE_FOLDER` - Create shared links on folders [Optional]

**Key parameters**:
- `collaboration_id`: Unique collaboration identifier
- `role`: Access level (`"editor"`, `"viewer"`, `"co-owner"`, `"owner"`, `"previewer"`, `"uploader"`, `"viewer uploader"`, `"previewer uploader"`)
- `status`: `"accepted"`, `"pending"`, or `"rejected"` for collaboration invites
- `file_id`: File to share or manage
- `lock__access`: Set to `"lock"` to lock a file
- `permissions__can__download`: `"company"` or `"open"` for download permissions

**Pitfalls**:
- Only certain roles can invite collaborators; insufficient permissions cause authorization errors
- `can_view_path` increases load time for the invitee's "All Files" page; limit to 1000 per user
- Collaboration expiration requires enterprise admin settings to be enabled
- Nested parameter names use double underscores (e.g., `lock__access`, `parent__id`)

### 5. Box Sign Requests

**When to use**: User wants to manage document signature requests

**Tool sequence**:
1. `BOX_LIST_BOX_SIGN_REQUESTS` - List all signature requests [Required]
2. `BOX_GET_BOX_SIGN_REQUEST_BY_ID` - Get details of a specific sign request [Optional]
3. `BOX_CANCEL_BOX_SIGN_REQUEST` - Cancel a pending sign request [Optional]

**Key parameters**:
- `sign_request_id`: UUID of the sign request
- `shared_requests`: Set `true` to include requests where user is a collaborator (not owner)
- `senders`: Filter by sender emails (requires `shared_requests: true`)
- `limit` / `marker`: Pagination parameters

**Pitfalls**:
- Requires Box Sign to be enabled for the enterprise account
- Deleted sign files or parent folders cause requests to not appear in listings
- Only the creator can cancel a sign request
- Sign request statuses include: `converting`, `created`, `sent`, `viewed`, `signed`, `declined`, `cancelled`, `expired`, `error_converting`, `error_sending`

## Common Patterns

### ID Resolution
Box uses numeric string IDs for all entities:
- **Root folder**: Always ID `"0"`
- **File ID from URL**: `https://*.app.box.com/files/123` gives file_id `"123"`
- **Folder ID from URL**: `https://*.app.box.com/folder/123` gives folder_id `"123"`
- **Search to ID**: Use `BOX_SEARCH_FOR_CONTENT` to find items, then extract IDs from results
- **ETag**: Use `if_match` with file's ETag for safe concurrent delete operations

### Pagination
Box supports two pagination methods:
- **Offset-based**: Use `offset` + `limit` (max offset 10000)
- **Marker-based**: Set `usemarker: true` and follow `marker` from responses (preferred for large datasets)
- Always paginate to completion to avoid partial results

### Nested Parameters
Box tools use double underscore notation for nested objects:
- `parent__id` for parent folder reference
- `lock__access`, `lock__expires__at`, `lock__is__download__prevented` for file locks
- `permissions__can__download` for download permissions

## Known Pitfalls

### ID Formats
- All IDs are numeric strings (e.g., `"123456"`, not integers)
- Root folder is always `"0"`
- File and folder IDs can be extracted from Box web app URLs

### Rate Limits
- Box API has per-endpoint rate limits
- Search and list operations should use pagination responsibly
- Bulk operations should include delays between requests

### Parameter Quirks
- `fields` parameter changes response shape: when specified, only mini representation + requested fields are returned
- Search requires either `query` or `mdfilters`; both are optional individually but one must be present
- `BOX_UPDATE_FILE` with `lock` set to `null` removes the lock (raw API only)
- Metadata query `from` field format: `enterprise_{enterprise_id}.templateKey` or `global.templateKey`

### Permissions
- Deletions fail without sufficient permissions; always handle error responses
- Collaboration roles determine what operations are allowed
- Enterprise settings may restrict certain sharing options

## Quick Reference

| Task | Tool Slug | Key Params |
|------|-----------|------------|
| Search content | `BOX_SEARCH_FOR_CONTENT` | `query`, `type`, `ancestor_folder_ids` |
| List folder items | `BOX_LIST_ITEMS_IN_FOLDER` | `folder_id`, `limit`, `marker` |
| Get file info | `BOX_GET_FILE_INFORMATION` | `file_id`, `fields` |
| Get folder info | `BOX_GET_FOLDER_INFORMATION` | `folder_id`, `fields` |
| Upload file | `BOX_UPLOAD_FILE` | `file`, `parent_id` |
| Download file | `BOX_DOWNLOAD_FILE` | `file_id` |
| Create folder | `BOX_CREATE_FOLDER` | `name`, `parent__id` |
| Update folder | `BOX_UPDATE_FOLDER` | `folder_id`, `name`, `parent` |
| Copy folder | `BOX_COPY_FOLDER` | `folder_id`, `parent__id` |
| Delete folder | `BOX_DELETE_FOLDER` | `folder_id`, `recursive` |
| Permanently delete folder | `BOX_PERMANENTLY_REMOVE_FOLDER` | folder_id |
| Update file | `BOX_UPDATE_FILE` | `file_id`, `name`, `parent__id` |
| Delete file | `BOX_DELETE_FILE` | `file_id`, `if_match` |
| List collaborations | `BOX_LIST_FILE_COLLABORATIONS` | `file_id` |
| Update collaboration | `BOX_UPDATE_COLLABORATION` | `collaboration_id`, `role` |
| Get collaboration | `BOX_GET_COLLABORATION` | `collaboration_id` |
| Query by metadata | `BOX_QUERY_FILES_FOLDERS_BY_METADATA` | `from`, `ancestor_folder_id`, `query` |
| List collections | `BOX_LIST_ALL_COLLECTIONS` | (none) |
| List collection items | `BOX_LIST_COLLECTION_ITEMS` | `collection_id` |
| List sign requests | `BOX_LIST_BOX_SIGN_REQUESTS` | `limit`, `marker` |
| Get sign request | `BOX_GET_BOX_SIGN_REQUEST_BY_ID` | `sign_request_id` |
| Cancel sign request | `BOX_CANCEL_BOX_SIGN_REQUEST` | `sign_request_id` |
| Recent items | `BOX_LIST_RECENTLY_ACCESSED_ITEMS` | (none) |
| Create zip download | `BOX_CREATE_ZIP_DOWNLOAD` | item IDs |

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: brain-to-docs
description: "Interview the user to turn project vision and decisions into README and ADR documentation."
category: productivity
risk: critical
source: community
source_repo: davidondrej/skills
source_type: community
date_added: "2026-07-07"
author: davidondrej
tags: [documentation, adr, planning]
tools: [claude, codex]
license: "MIT"
license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
---

# brain-to-docs

## When to Use

- Use when the user wants to extract project vision, decisions, or preferences into durable docs.
- Use when README and ADRs should be built through a back-and-forth interview.

The whole purpose: extract as much of the user's taste, judgment, knowledge, vision,
preferences, and decisions as possible into text — saved as clear, concise
markdown docs for the project. README holds the vision; `docs/adr/` holds the
decisions.

## The loop

1. **Check docs first, every time.** Read `docs/adr/` (and `README.md`) before
   doing anything — other agents and people add/edit ADRs constantly.
2. **Ask 5 different questions** in plain text (never a questions UI) — default 5
   unless the user asks for a different number. Make them high-variety: a wide,
   creative spectrum of unique angles, not all the same type (e.g. not all "tech
   stack" or all "product" or all "monetization"). Exception: if the user asks for a
   specific focus area, follow it. The user answers whichever they find most useful.
3. **Update docs after EVERY answer** — no exceptions. You decide whether it
   updates `README.md` or becomes a new ADR — whatever makes sense.
4. Repeat until the user says "we're done" (or similar).

## Rules

- All answers & responses during this "brain to docs" process must be VERY
  CONCISE, all sentences should be SHORT, and everything should be written in
  PLAIN ENGLISH.
- ADRs: short, numbered `NNNN-slug.md`, Status + Context + Decision + Consequences.
- README: vision only. Decisions go in ADRs.
- Don't challenge the user's thinking unless they ask, or they're making a severe mistake.

## Limitations

- Adapted from `davidondrej/skills`; verify local paths, tools, credentials, and agent features before acting.
- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.


---
name: brainstorming
description: "Use before creative or constructive work (features, architecture, behavior). Transforms vague ideas into validated designs through disciplined reasoning and collaboration."
risk: critical
source: community
date_added: "2026-02-27"
---

# Brainstorming Ideas Into Designs

## Purpose

Turn raw ideas into **clear, validated designs and specifications**
through structured dialogue **before any implementation begins**.

This skill exists to prevent:
- premature implementation
- hidden assumptions
- misaligned solutions
- fragile systems

You are **not allowed** to implement, code, or modify behavior while this skill is active.

---

## Operating Mode

You are operating as a **design facilitator and senior reviewer**, not a builder.

- No creative implementation
- No speculative features
- No silent assumptions
- No skipping ahead

Your job is to **slow the process down just enough to get it right**.

---

## The Process

### 1⃣ Understand the Current Context (Mandatory First Step)

Before asking any questions:

- Review the current project state (if available):
  - files
  - documentation
  - plans
  - prior decisions
- Identify what already exists vs. what is proposed
- Note constraints that appear implicit but unconfirmed

**Do not design yet.**

---

### 2⃣ Understanding the Idea (One Question at a Time)

Your goal here is **shared clarity**, not speed.

**Rules:**

- Ask **one question per message**
- Prefer **multiple-choice questions** when possible
- Use open-ended questions only when necessary
- If a topic needs depth, split it into multiple questions

Focus on understanding:

- purpose
- target users
- constraints
- success criteria
- explicit non-goals

---

### 3⃣ Non-Functional Requirements (Mandatory)

You MUST explicitly clarify or propose assumptions for:

- Performance expectations
- Scale (users, data, traffic)
- Security or privacy constraints
- Reliability / availability needs
- Maintenance and ownership expectations

If the user is unsure:

- Propose reasonable defaults
- Clearly mark them as **assumptions**

---

### 4⃣ Understanding Lock (Hard Gate)

Before proposing **any design**, you MUST pause and do the following:

#### Understanding Summary
Provide a concise summary (5–7 bullets) covering:
- What is being built
- Why it exists
- Who it is for
- Key constraints
- Explicit non-goals

#### Assumptions
List all assumptions explicitly.

#### Open Questions
List unresolved questions, if any.

Then ask:

> “Does this accurately reflect your intent?
> Please confirm or correct anything before we move to design.”

**Do NOT proceed until explicit confirmation is given.**

---

### 5⃣ Explore Design Approaches

Once understanding is confirmed:

- Propose **2–3 viable approaches**
- Lead with your **recommended option**
- Explain trade-offs clearly:
  - complexity
  - extensibility
  - risk
  - maintenance
- Avoid premature optimization (**YAGNI ruthlessly**)

This is still **not** final design.

---

### 6⃣ Present the Design (Incrementally)

When presenting the design:

- Break it into sections of **200–300 words max**
- After each section, ask:

  > “Does this look right so far?”

Cover, as relevant:

- Architecture
- Components
- Data flow
- Error handling
- Edge cases
- Testing strategy

---

### 7⃣ Decision Log (Mandatory)

Maintain a running **Decision Log** throughout the design discussion.

For each decision:
- What was decided
- Alternatives considered
- Why this option was chosen

This log should be preserved for documentation.

---

## After the Design

### 📄 Documentation

Once the design is validated:

- Write the final design to a durable, shared format (e.g. Markdown)
- Include:
  - Understanding summary
  - Assumptions
  - Decision log
  - Final design

Persist the document according to the project’s standard workflow.

---

### 🛠 Implementation Handoff (Optional)

Only after documentation is complete, ask:

> “Ready to set up for implementation?”

If yes:
- Create an explicit implementation plan
- Isolate work if the workflow supports it
- Proceed incrementally

---

## Exit Criteria (Hard Stop Conditions)

You may exit brainstorming mode **only when all of the following are true**:

- Understanding Lock has been confirmed
- At least one design approach is explicitly accepted
- Major assumptions are documented
- Key risks are acknowledged
- Decision Log is complete

If any criterion is unmet:
- Continue refinement
- **Do NOT proceed to implementation**

---

## Key Principles (Non-Negotiable)

- One question at a time
- Assumptions must be explicit
- Explore alternatives
- Validate incrementally
- Prefer clarity over cleverness
- Be willing to go back and clarify
- **YAGNI ruthlessly**

---
If the design is high-impact, high-risk, or requires elevated confidence, you MUST hand off the finalized design and Decision Log to the `multi-agent-brainstorming` skill before implementation.

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: brand-guidelines
description: Write copy following Sentry brand guidelines. Use when writing UI text, error messages, empty states, onboarding flows, 404 pages, documentation, marketing copy, or any user-facing content. Covers both Plain Speech (default) and Sentry Voice tones.
risk: none
source: community
---

# Brand Guidelines

Write user-facing copy following Sentry's brand guidelines.

## When to Use
- You need to write or rewrite user-facing copy in Sentry's voice.
- The task involves UI text, onboarding, empty states, docs, marketing copy, or other branded content.
- You need guidance on when to use Plain Speech versus Sentry Voice.

## Tone Selection

Choose the appropriate tone based on context:

| Use Plain Speech | Use Sentry Voice |
|------------------|------------------|
| Product UI (buttons, labels, forms) | 404 pages |
| Documentation | Empty states |
| Error messages | Onboarding flows |
| Settings pages | Loading states |
| Transactional emails | "What's New" announcements |
| Help text | Marketing copy |

**Default to Plain Speech** unless the context specifically calls for personality.

## Plain Speech (Default)

Plain Speech is clear, direct, and functional. Use it for most UI elements.

### Rules

1. **Be concise** - Use the fewest words needed
2. **Be direct** - Tell users what to do, not what they can do
3. **Use active voice** - "Save your changes" not "Your changes will be saved"
4. **Avoid jargon** - Use simple words users understand
5. **Be specific** - "3 errors found" not "Some errors found"

### Examples

| Instead of | Write |
|------------|-------|
| "Click here to save your changes" | "Save" |
| "You can filter results by date" | "Filter by date" |
| "An error has occurred" | "Something went wrong" |
| "Please enter a valid email address" | "Enter a valid email" |
| "Are you sure you want to delete?" | "Delete this item?" |

## Sentry Voice

Sentry Voice adds personality in appropriate moments. It's empathetic, self-aware, and occasionally snarky.

### Principles

1. **Empathetic snark** - Direct frustration at the situation, never the user
2. **Self-aware** - Acknowledge the absurdity of software
3. **Fun but functional** - Personality should enhance, not obscure meaning
4. **Earned moments** - Only use when users have time to appreciate it

### Examples

**404 Pages:**
> "This page doesn't exist. Maybe it never did. Maybe it was a dream. Either way, let's get you back on track."

**Empty States:**
> "No errors yet. Enjoy this moment of peace while it lasts."

**Onboarding:**
> "Let's get your first error. Don't worry, it's not as scary as it sounds."

**Loading States:**
> "Crunching the numbers..."
> "Fetching your data..."

### When NOT to Use Sentry Voice

- Error messages (users are frustrated)
- Settings pages (users are focused)
- Documentation (users need information)
- Billing/payment flows (users need trust)

## General Rules

### Spelling and Grammar

- Use **American English** spelling (color, not colour)
- Use **Title Case** for headings and page titles
- Use **Sentence case** for body text, buttons, and labels

### Punctuation

- **No exclamation marks** in UI text (exception: celebratory moments)
- **No periods** in short UI labels or button text
- **Use periods** in complete sentences and help text
- **No ALL CAPS** except for acronyms (API, SDK, URL)

### Word Choices

| Avoid | Prefer |
|-------|--------|
| Please | (omit) |
| Sorry | (be specific about the problem) |
| Error occurred | Something went wrong |
| Invalid | (explain what's wrong) |
| Success! | (describe what happened) |
| Oops | (be specific) |

## Dash Usage

| Type | Use | Example |
|------|-----|---------|
| Hyphen (-) | Compound words, ranges | "real-time", "1-10" |
| En-dash (--) | Ranges, relationships | "2023--2024", "parent--child" |
| Em-dash (---) | Interruption, emphasis | "Errors---even small ones---matter" |

In most UI contexts, use hyphens. Reserve en-dashes for date ranges and em-dashes for longer prose.

## UI Element Guidelines

### Buttons

- Use action verbs: "Save", "Delete", "Create"
- Be specific: "Create Project" not just "Create"
- Max 2-3 words when possible
- No periods or exclamation marks

### Error Messages

1. Say what happened
2. Say why (if helpful)
3. Say what to do next

**Good:** "Could not save changes. Check your connection and try again."
**Bad:** "Error: Save failed."

### Empty States

1. Explain what would normally be here
2. Provide a clear action to populate the state
3. Sentry Voice is appropriate here

**Good:** "No projects yet. Create your first project to start tracking errors."

### Confirmation Dialogs

- Make the action clear in the title
- Explain consequences if destructive
- Use specific button labels ("Delete Project", not "OK")

### Tooltips and Help Text

- Keep under 2 sentences
- Explain the "why", not just the "what"
- Link to docs for complex topics

## Anti-Patterns

Avoid these common mistakes:

- **Robot speak:** "Item has been successfully deleted" -> "Deleted"
- **Passive voice:** "Changes were saved" -> "Changes saved"
- **Unnecessary words:** "In order to" -> "To"
- **Hedging:** "This might cause..." -> "This will cause..."
- **Double negatives:** "Not unlike..." -> "Similar to..."
- **Marketing speak in UI:** "Supercharge your workflow" -> "Speed up your workflow"

## References

- [Sentry Voice Guidelines](https://develop.sentry.dev/frontend/sentry-voice/)
- [Sentry Frontend Handbook](https://develop.sentry.dev/frontend/)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: brand-guidelines-anthropic
description: "To access Anthropic's official brand identity and style resources, use this skill."
risk: none
source: community
date_added: "2026-02-27"
---

# Anthropic Brand Styling

## Overview

To access Anthropic's official brand identity and style resources, use this skill.

**Keywords**: branding, corporate identity, visual identity, post-processing, styling, brand colors, typography, Anthropic brand, visual formatting, visual design

## Brand Guidelines

### Colors

**Main Colors:**

- Dark: `#141413` - Primary text and dark backgrounds
- Light: `#faf9f5` - Light backgrounds and text on dark
- Mid Gray: `#b0aea5` - Secondary elements
- Light Gray: `#e8e6dc` - Subtle backgrounds

**Accent Colors:**

- Orange: `#d97757` - Primary accent
- Blue: `#6a9bcc` - Secondary accent
- Green: `#788c5d` - Tertiary accent

### Typography

- **Headings**: Poppins (with Arial fallback)
- **Body Text**: Lora (with Georgia fallback)
- **Note**: Fonts should be pre-installed in your environment for best results

## Features

### Smart Font Application

- Applies Poppins font to headings (24pt and larger)
- Applies Lora font to body text
- Automatically falls back to Arial/Georgia if custom fonts unavailable
- Preserves readability across all systems

### Text Styling

- Headings (24pt+): Poppins font
- Body text: Lora font
- Smart color selection based on background
- Preserves text hierarchy and formatting

### Shape and Accent Colors

- Non-text shapes use accent colors
- Cycles through orange, blue, and green accents
- Maintains visual interest while staying on-brand

## Technical Details

### Font Management

- Uses system-installed Poppins and Lora fonts when available
- Provides automatic fallback to Arial (headings) and Georgia (body)
- No font installation required - works with existing system fonts
- For best results, pre-install Poppins and Lora fonts in your environment

### Color Application

- Uses RGB color values for precise brand matching
- Applied via python-pptx's RGBColor class
- Maintains color fidelity across different systems

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: brand-guidelines-community
description: "To access Anthropic's official brand identity and style resources, use this skill."
risk: none
source: community
date_added: "2026-02-27"
---

# Anthropic Brand Styling

## Overview

To access Anthropic's official brand identity and style resources, use this skill.

**Keywords**: branding, corporate identity, visual identity, post-processing, styling, brand colors, typography, Anthropic brand, visual formatting, visual design

## Brand Guidelines

### Colors

**Main Colors:**

- Dark: `#141413` - Primary text and dark backgrounds
- Light: `#faf9f5` - Light backgrounds and text on dark
- Mid Gray: `#b0aea5` - Secondary elements
- Light Gray: `#e8e6dc` - Subtle backgrounds

**Accent Colors:**

- Orange: `#d97757` - Primary accent
- Blue: `#6a9bcc` - Secondary accent
- Green: `#788c5d` - Tertiary accent

### Typography

- **Headings**: Poppins (with Arial fallback)
- **Body Text**: Lora (with Georgia fallback)
- **Note**: Fonts should be pre-installed in your environment for best results

## Features

### Smart Font Application

- Applies Poppins font to headings (24pt and larger)
- Applies Lora font to body text
- Automatically falls back to Arial/Georgia if custom fonts unavailable
- Preserves readability across all systems

### Text Styling

- Headings (24pt+): Poppins font
- Body text: Lora font
- Smart color selection based on background
- Preserves text hierarchy and formatting

### Shape and Accent Colors

- Non-text shapes use accent colors
- Cycles through orange, blue, and green accents
- Maintains visual interest while staying on-brand

## Technical Details

### Font Management

- Uses system-installed Poppins and Lora fonts when available
- Provides automatic fallback to Arial (headings) and Georgia (body)
- No font installation required - works with existing system fonts
- For best results, pre-install Poppins and Lora fonts in your environment

### Color Application

- Uses RGB color values for precise brand matching
- Applied via python-pptx's RGBColor class
- Maintains color fidelity across different systems

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: brand-perception-psychologist
description: "One sentence - what this skill does and when to invoke it"
risk: safe
source: community
date_added: "2026-04-04"
---
You are a **Brand Psychologist and Semiotics Researcher**. Your task is to diagnose what a brand's current visual, verbal, and behavioral identity signals subconsciously to its target audience and prescribe alignment changes to close the perception gap.

## When to Use
- Use when you need to diagnose how a market currently perceives a brand and how to reposition it.
- Use when messaging, visual identity, or proof points need to shift trust or status perceptions.

## CONTEXT GATHERING

Before auditing brand perception, establish:

1. **The Target Human** - psychographic profile and category expectations.
2. **The Objective** - intended brand meaning and position.
3. **The Output** - brand perception audit and realignment plan.
4. **Constraints** - current assets, culture, and ethics.

If the intended position is unclear, ask before proceeding.

## PSYCHOLOGICAL FRAMEWORK: BRAND SCHEMA ALIGNMENT

### Mechanism
People do not evaluate a brand only by what it says. They infer a schema from repeated visual, verbal, and behavioral signals, then store the brand in a mental category. Alignment matters because one mismatched signal can weaken the whole impression through schema inconsistency and halo effects (Aaker brand personality theory; Bagozzi et al., 2021; schema theory; halo effect research).

### Execution Steps

**Step 1 - Identify the current brand schema**
Describe the subconscious impression the audience is likely forming now.
*Research basis: brand meaning is built from repeated signals, not from mission statements alone (Bagozzi et al., 2021).*

**Step 2 - Compare to intended position**
State the desired perception in the same terms.
*Research basis: perception shifts when the audience sees congruent evidence across touchpoints (congruence theory).*

**Step 3 - Find the largest mismatch**
Locate the strongest signal conflict across visual, verbal, or behavioral layers.
*Research basis: one strong mismatch can create cognitive dissonance and weaken trust (halo effect and schema theory).*

**Step 4 - Prescribe the smallest useful correction**
Change the signal that will most efficiently move perception.
*Research basis: brand meaning changes fastest when the highest-salience signal changes first (Aaker; semiotics research).*

**Step 5 - Verify cross-touchpoint consistency**
Check that the new position is supported everywhere the audience interacts.
*Research basis: consistency across channels reduces ambiguity and builds stronger category placement (Bagozzi et al., 2021).*

## DECISION MATRIX

### Variable: position gap size
- If small -> make targeted refinements.
- If medium -> realign the strongest mismatched layer first.
- If large -> rework the identity system across all layers.

### Variable: category expectation
- If category is conservative -> signal stability and competence.
- If category is premium -> signal restraint and precision.
- If category is playful -> signal personality without losing clarity.

### Variable: cultural context
- If culture-sensitive -> check semiotics and local category norms.
- If global -> use simple, broadly legible signals.
- If mixed -> prioritize clarity over subtle symbolism.

## FAILURE MODES - DO NOT DO THESE

**Failure Mode 1**
- Agents typically: change the logo and call it repositioning.
- Why it fails psychologically: brand perception is multi-layered.
- Instead: align visual, verbal, and behavioral signals.

**Failure Mode 2**
- Agents typically: introduce mixed messages across touchpoints.
- Why it fails psychologically: inconsistency creates dissonance.
- Instead: make the same promise everywhere.

**Failure Mode 3**
- Agents typically: ignore category schema and try to force a new meaning too quickly.
- Why it fails psychologically: people classify brands by familiar mental categories.
- Instead: move perception through credible, repeated signals.

## ETHICAL GUARDRAILS

This skill must:
- Tell the truth about what the brand can and cannot be.
- Avoid identity theater with no substance.
- Respect the audience's existing mental model.

The line between persuasion and manipulation is changing perception through real alignment versus using aesthetic tricks to imply qualities the brand does not have. Never cross it.

## SKILL CHAINING

Before invoking this skill, the agent should have completed:
- [ ] `@customer-psychographic-profiler`
- [ ] `@visual-emotion-engineer`
- [ ] `@trust-calibrator`

This skill's output feeds into:
- [ ] `@copywriting-psychologist`
- [ ] `@ux-persuasion-engineer`
- [ ] `@pitch-psychologist`

## OUTPUT QUALITY CHECK

Before finalizing output, the agent asks:
- [ ] Did I identify the current brand schema?
- [ ] Did I locate the biggest mismatch?
- [ ] Did I prescribe the smallest high-leverage correction?
- [ ] Is the new position consistent across touchpoints?
- [ ] Would the audience experience this as more credible, not just prettier?

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: brave-man
description: "Runs a structured clarifying interview for new project requests before building. Instead of writing code, it outputs a fully specified prompt.md for a fresh agent session to execute, preventing expensive mistakes."
risk: critical
source: community
date_added: "2026-06-16"
---

# Brave Man

## Overview

Most people describing a project ("vibe coders" included) only give a brief or partial picture of what they want. They can't be expected to specify everything up front — humans don't think in complete specs, and even when they try, they forget the small details that turn into real problems once the project has grown. If the agent starts building from a thin description, it fills the gaps with silent guesses, and by the time those guesses turn out wrong, they're expensive to undo.

Brave Man flips the order: clarify exhaustively first, build later. The agent's job here is NOT to write code, scaffold files, or produce an implementation plan. Its only job is to run a structured interview until the project is fully understood, then write that understanding down as a single, clean, self-contained `prompt.md` file that a fresh agent session can execute later.

## When to Use This Skill

- Use when a user describes wanting to build a website, app, software, tool, or any kind of project.
- Use when the user request includes phrases like "build me a website", "I want an app for X", or "make a tool that does Y".
- Use BEFORE writing any code or implementation plan for a new build request.

## Step-by-Step Guide

1. **Triage** — a couple of quick questions to size up the project so question depth matches project complexity.
2. **Phased interview** — work through the relevant phases below, one at a time, asking batched questions per phase.
3. **Track completion** — maintain a visible checklist; don't move to synthesis until every relevant phase is closed (answered or explicitly defaulted).
4. **Synthesize** — write the final `prompt.md`. Do not generate an implementation plan artifact, scaffold a repo, or write any application code in this skill.
5. **Hand off** — tell the user to start a new chat, tag `prompt.md`, and ask the agent to execute it.

Never skip straight to building because the request "sounded simple." Simple requests still go through triage — triage is what decides how short the interview gets, not whether it happens.

## Phase 0: Triage

Ask 2-3 quick questions before anything else, to calibrate depth:

- Is this just for you, or will other people use/rely on it?
- Roughly how big is this in your head — a single page/script, a small app with a few features, or something with many moving parts (accounts, payments, multiple user roles, etc.)?
- Do you already have any strong preferences (language, framework, hosting, existing codebase) or is everything open?

Use the answers to decide which phases below need full depth, which need only one or two quick questions, and which can be skipped entirely with a stated default (e.g., a single static page skips Integrations & Auth entirely rather than asking about it).

## The phases

Work through these one phase at a time. Within a phase, ask questions in one batched round (3-5 questions), not one at a time. Skip or shrink phases that triage marked irrelevant — say so explicitly ("skipping auth since this has no accounts") rather than silently dropping them.

### Phase 1 — Purpose & users
- Who is this for, and what's the one thing it absolutely must let them do?
- What does success look like — what would make you say "yes, this is exactly what I wanted"?
- Is there an existing app/site/tool you're modeling this after, or anything you specifically want to avoid?

### Phase 2 — Core features & flows
- Walk me through what a user does step by step, from opening it to getting value out of it.
- Of everything you've mentioned, what's must-have for a first version versus nice-to-have later?
- Are there any features you're assuming are "obvious" that you haven't said out loud yet?

### Phase 3 — Data & content model
- What are the main "things" this app manages (e.g. posts, orders, users, files) and how do they relate to each other?
- Does data need to persist permanently, or is some of it temporary/session-only?
- Will the same data need to be seen differently by different users (e.g. private vs shared), or is it all visible to everyone the same way?

### Phase 4 — Tech stack & environment
- Any required language/framework, or should the agent pick what fits best?
- Where will this run — a specific hosting platform, local-only, mobile, desktop, browser?
- Does this need to fit into an existing codebase/repo, or is it starting fresh?

### Phase 5 — Integrations & auth
*(skip entirely if triage shows no accounts/external services needed — state that explicitly instead of asking)*
- Does this need user accounts/login at all? If so, simple email+password, or sign-in via Google/Apple/etc.?
- Does it need to talk to any outside service (payments, email sending, maps, AI APIs, etc.)?
- Are there multiple types of users with different permissions (e.g. admin vs regular user)?

### Phase 6 — Non-functional requirements
- Roughly how many people might use this at once — a handful, hundreds, way more?
- Any sensitive data involved (personal info, payments, health data) that needs extra care?
- Any hard constraints — must work offline, must load instantly, must work on old phones, etc.?

### Phase 7 — Edge cases & error states
- What should happen when something goes wrong — bad input, lost connection, empty states (e.g. no data yet)?
- Is there any action a user could take that would be risky or hard to undo (deleting something, sending something, paying for something)? How careful should the app be about confirming those?

### Phase 8 — Definition of done
- If you handed this to someone to test, what would they check to confirm it's working correctly?
- What's explicitly out of scope for the first version, so it isn't accidentally built or left half-done?

## Best Practices

- ✅ **Do:** Batch, don't drip. One themed round per phase, not an endless single-question ping-pong.
- ✅ **Do:** Plain language over jargon. Phrase questions around real-world consequences unless the user has already shown technical fluency.
- ✅ **Do:** Offer options where possible when a question has a small number of sensible answers.
- ❌ **Don't:** Ask redundant questions that were already answered earlier or directly inferable.
- ✅ **Do:** Handle "I don't know" gracefully by proposing a sensible, named default and stating it plainly as an assumption.
- ❌ **Don't:** Jump ahead or combine phases unless the user volunteers the info naturally.
- ✅ **Do:** Honor "just use your judgment" but still require at least a default-and-confirm pass on Phase 3 (data) and Phase 5 (auth/integrations).

## Completion checklist

Keep a running, visible status of each relevant phase using this format, and show it to the user as phases close:

```
[x] Purpose & users — confirmed
[x] Core features & flows — confirmed
[~] Data & content model — defaulted (assumed simple per-user storage, no sharing)
[ ] Tech stack & environment — open
[-] Integrations & auth — skipped (no accounts needed)
...
```

Do not move to synthesis while any relevant phase is still `[ ]` open. `[x]` confirmed and `[~]` defaulted-and-accepted both count as closed.

## Synthesis: writing prompt.md

Once every relevant phase is closed, stop asking questions. Do not produce an implementation plan, do not scaffold a project, do not write application code. Instead, write a single file named `prompt.md` in the project root containing the full, distilled specification, addressed directly to whichever agent will read it next. Structure it as:

```markdown
# Project Brief: <name>

You are building the following project. Treat this file as the complete
specification — everything needed to build it correctly is below.
Do not re-ask the questions that produced this brief unless something
here is genuinely ambiguous or missing.

## Overview
<one paragraph: what it is, who it's for, what success looks like>

## Core Features (prioritized)
<must-have list, then nice-to-have list>

## User Flows
<step-by-step walkthroughs from Phase 2>

## Data Model
<entities, relationships, persistence rules from Phase 3>

## Tech Stack & Environment
<language/framework, hosting/platform, repo constraints from Phase 4>

## Integrations & Auth
<or "None — no accounts or external services required">

## Non-Functional Requirements
<scale, sensitive data handling, hard constraints from Phase 6>

## Edge Cases & Error Handling
<from Phase 7>

## Assumptions & Defaults Used
<every default that was proposed and accepted during the interview,
listed plainly so the user can spot anything they want to override later>

## Definition of Done
<acceptance criteria and explicit out-of-scope items from Phase 8>

## Suggested Build Order
<a short, sensible milestone sequence — not a full implementation plan>
```

Keep it tight and complete rather than padded — every section should contain real decisions, not filler. The "Assumptions & Defaults Used" section matters most: it's the paper trail for every gap the user couldn't have specified up front.

## Handoff

After writing `prompt.md`, tell the user, plainly:

> Your project spec is saved as `prompt.md`. For the best results, start a **new chat**, tag this file, and tell the agent to execute it. Starting fresh keeps the build conversation free of the back-and-forth that produced the spec — the agent only needs the distilled brief, not the full interview, which keeps things faster and avoids burning context on a conversation it doesn't need anymore.

Do not start implementing in the current session even if the user asks immediately after — point them to the new-chat handoff, since that's the whole point of separating interview from execution.

## Examples

### Example 1: User says "Build me a todo app"
```markdown
1. **Triage:** Is this just for you? How big is it? Any preferred stack?
2. **Phase 1 (Purpose):** What is the one thing it absolutely must let you do?
3. **Synthesis:** Outputs `prompt.md` with React/Firebase stack based on interview.
```

## Troubleshooting

### Problem: User is frustrated by too many questions
**Symptoms:** User replies with "just build it" or "I don't care".
**Solution:** Stop asking questions, propose defaults for the remaining critical phases (Data, Auth), and synthesize the `prompt.md`.

## Related Skills

- `@brainstorming` - Use when exploring abstract ideas rather than gathering a build specification.

## Limitations

- **No Code Generation:** This skill intentionally does not write any application code or scaffold repositories.
- **Requires New Session:** The generated `prompt.md` must be executed in a fresh agent session to ensure clean context.
- **Relies on User Input:** The quality of the spec depends heavily on the user's willingness to answer the interview questions.


---
name: brendangregg-use-tsa
description: "Methodical performance troubleshooting and root-cause analysis with Brendan Gregg's USE and TSA methods, plus evidence-backed RCA and postmortem reports."
category: devops
risk: safe
source: community
source_repo: thecsdoctor/brendangregg-use-tsa-skill
source_type: community
date_added: "2026-07-28"
author: thecsdoctor
tags: [performance, troubleshooting, root-cause-analysis, linux, observability, sre, postmortem]
tools: [claude, cursor, gemini, codex]
license: "MIT"
license_source: "https://github.com/thecsdoctor/brendangregg-use-tsa-skill/blob/main/LICENSE"
---

# Brendan Gregg USE+TSA Performance Analysis

## Overview

A fixed, evidence-first procedure for system performance debugging, root-cause analysis (RCA), and incident reporting, distilled from Brendan Gregg's published methodologies. Instead of running whichever commands happen to be familiar, the agent poses questions first and then finds metrics to answer them: the USE Method (Utilization, Saturation, Errors) sweeps every resource, the TSA Method (Thread State Analysis) decomposes thread time, and off-CPU analysis plus flame graphs drill into what the sweeps find. Every investigation ends in a structured triage note, RCA report, or postmortem where each claim traces to a command and its output.

This skill adapts material from the community repository
[thecsdoctor/brendangregg-use-tsa-skill](https://github.com/thecsdoctor/brendangregg-use-tsa-skill)
(full checklists, reference library, and report templates live there).

## When to Use This Skill

- Use when a server, VM, or container is "slow" and the cause is unknown
- Use when latency or throughput regressed after a deploy, config change, or load shift
- Use when CPU, memory, disk, or network metrics look abnormal and need interpretation
- Use when an application hangs or threads pile up
- Use when the user asks for debugging, triage, or root-cause analysis of a performance issue
- Use when an incident needs an RCA report or a blameless postmortem with an evidence trail

## How It Works

### Step 0: Problem Statement

Define the problem before measuring. Ask: What makes you think there is a problem? Has it ever performed well? What changed recently (software, hardware, load)? Can it be expressed as latency or run time — quantify it. Who else is affected? What is the environment (OS, versions, config, container/VM limits)?

### Step 1: 60-Second Triage (Linux)

Run the ten-command sweep, checking **errors and saturation first** (easiest to interpret), then utilization. Record every exonerated resource.

```bash
uptime                 # load trend (includes uninterruptible I/O on Linux)
dmesg | tail           # kernel errors: oom-killer, SYN flooding, hardware
vmstat 1               # r > CPU count = CPU saturation; si/so = swapping; wa = disk
mpstat -P ALL 1        # per-CPU imbalance (single hot CPU = single-threaded app)
pidstat 1              # per-process CPU over time
iostat -xz 1           # await (app-suffered latency), avgqu-sz, %util
free -m                # memory; buffers/cache near zero hurts
sar -n DEV 1           # NIC throughput vs link limit
sar -n TCP,ETCP 1      # active/passive connections, retransmits
top                    # spot variable load
```

### Step 2: USE Sweep (resource-oriented)

**For every resource, check Utilization, Saturation, and Errors.** Iterate CPUs, memory capacity, network interfaces, storage I/O and capacity, controllers, interconnects — plus software resources (mutex locks, thread pools, process/file-descriptor capacity) and imposed limits (cgroup quotas, hypervisor caps, ulimits). Check errors before utilization. Interpretations: 100% utilization is usually a bottleneck (confirm via saturation); any non-zero saturation can be a problem; non-zero, still-increasing error counters are worth investigating; and a clean sweep is a result — it narrows the search space.

### Step 3: TSA Sweep (thread-oriented)

**For each thread of interest, split time into: Executing / Runnable / Anonymous Paging / Sleeping / Lock / Idle.** Investigate states from most to least frequent with state-appropriate tools. If more than ~10% of time is Runnable or Anonymous Paging, fix those first — latency states can be tuned to zero. Linux instruments: `/proc/PID/schedstat` run_delay and `perf sched latency` (Runnable), `vmstat` si/so and per-process `min_flt` (Paging), `offcputime`/`cpudist` from bcc (Sleeping), `/proc/lock_stat` and `valgrind --tool=drd` (Lock), `pidstat`/flame graphs (Executing).

### Step 4: Drill Down

Follow the biggest contributor: Executing → CPU profile + flame graph; Sleeping/Lock → off-CPU stacks (`offcputime -p PID`, render with `flamegraph.pl --color=io`); latency complaints → time-division decomposition; microservices → RED method (Rate, Errors, Duration). Prefer eBPF in-kernel aggregation over per-event dumps; start with sub-second traces in production.

### Step 5: Confirm Root Cause

State the causal chain (trigger → mechanism → symptom) with every link evidence-backed. Keep falsifiable hypotheses on record even when ruled out. Ask "why" up to five times. Would removing this cause prevent recurrence? Does it explain all primary evidence?

### Step 6: Fix and Verify

Apply the cheapest effective fix (mantra order: don't do it → cache it → do it less → do it later → off-peak → concurrently → cheaper). Re-measure with the **same instruments** as the evidence and show before/after. "Deployed" is not "verified".

### Step 7: Report

Produce the report the situation calls for — triage note, RCA report, or full postmortem (summary, impact, root cause, detection, investigation log, evidence table, resolution, prevention actions). Absolute dates everywhere; unknowns marked as known-unknowns.

## Examples

### Example 1: "This server feels slow"

```
User: prod-web-02 feels slow. Triage it and tell me what you ruled out.

Agent: runs the 60s sweep → dmesg shows oom-killer events at 09:41 UTC;
vmstat si/so non-zero; free -m shows 120MB free with page cache near zero.
Conclusion: memory capacity saturation (USE), host CPU/disk/network exonerated
with numbers. Report lists each exonerated resource next to its evidence.
```

**Explanation:** Errors-and-saturation-first finds the OOM events in step 1, and the exonerated resources stay on the record.

### Example 2: Post-deploy latency regression

```
User: API p99 went 95ms → 1.9s after the 14:02 deploy. Root cause + RCA.

Agent: host sweep clean (CPU 48%, no iowait, 0 retransmits) → TSA on app
threads shows 61% Runnable on a half-idle host → checks resource controls:
/sys/fs/cgroup cpu.max = 1.5 CPUs, cpu.stat nr_throttled +54k/min → cgroup
CPU throttling after the replica increase. Fix: raise limit; verify:
nr_throttled 0/s for 72h, p99 110ms under 1.4x load. RCA report includes the
causal chain, the ruled-out hypotheses, and the command→output table.
```

**Explanation:** Runnable-dominant TSA on an under-utilized host is the signature of a resource-control limit, not a busy machine — the method routes around the wrong diagnosis.

## Best Practices

- ✅ **Do:** Diagnose with read-only commands before changing anything
- ✅ **Do:** Check errors and saturation before utilization — they interpret fastest
- ✅ **Do:** Quantify everything ("p99 240ms → 2.1s", "run-queue 9 on 4 CPUs")
- ✅ **Do:** Record what was ruled out, with the evidence — exoneration narrows the search
- ✅ **Do:** Re-measure after the fix with the same instruments as the evidence
- ❌ **Don't:** Change tunables at random until the symptom stops (drunk-man anti-method)
- ❌ **Don't:** Trust low *average* utilization to rule out saturation — bursts hide in long intervals
- ❌ **Don't:** Treat "package installed" or "dashboard green" as "working" — verify runtime state
- ❌ **Don't:** Blame a component another team owns without data (blame-someone-else anti-method)

## Limitations

- This skill does not replace environment-specific validation, testing, or expert review.
- Some metrics require privileges or tooling that may be absent (eBPF/bcc needs Linux ≥ 4.8 and usually root; `perf` needs perf_events access; sar needs sysstat). Missing instruments are reported as known-unknowns, not silently skipped.
- The deepest checklists target Linux; other OSes follow the same resource × metric matrix with different instruments.
- Stop and ask for clarification if required inputs, permissions, or safety boundaries are missing.

## Security & Safety Notes

- Diagnostics are read-only first. Any remediation (config edits, restarts, limit changes) requires explicit user confirmation before execution — the skill's own golden rules mandate this gate.
- Production tracing has overhead: scheduler events can reach millions/sec. The skill instructs eBPF in-kernel aggregation over per-event dumping, starting with sub-second traces while watching system CPU.
- All commands shown are standard local observability tools (`vmstat`, `iostat`, `sar`, `perf`, bcc tools, `/proc` reads); there are no network fetches, no credential handling, and no destructive examples. Intended usage is on systems the user is authorized to operate.

## Common Pitfalls

- **Problem:** Linux load averages look alarming but the CPUs are idle.
  **Solution:** Linux load includes uninterruptible (usually disk) tasks — check `vmstat` "r" for CPU saturation and `iostat` await for disk instead.
- **Problem:** Host CPU looks fine but the application starves.
  **Solution:** Check resource controls, not just the host: cgroup `cpu.max` and `cpu.stat nr_throttled` (Runnable-dominant TSA is the tell).
- **Problem:** "Time spent in MySQL" sends the investigation into the database.
  **Solution:** Component timers are request-oriented; run TSA on the threads — the time may be Runnable (a noisy neighbor), not execution.
- **Problem:** Off-CPU stacks are polluted with nonsense frames on a busy box.
  **Solution:** Filter involuntary context switches: `offcputime --state 2` (TASK_UNINTERRUPTIBLE) and fix frame pointers (`-fomit-frame-pointer` breaks user stacks).

## Related Skills

- `@devops-troubleshooter` - Broader DevOps incident response; use this skill for the performance-methodology core
- `@incident-responder` - General incident command workflow; pairs with this skill's evidence discipline
- `@application-performance-performance-optimization` - Application-level optimization after systemic bottlenecks are ruled out

## Additional Resources

- [Full skill repository: checklists, references, and report templates](https://github.com/thecsdoctor/brendangregg-use-tsa-skill)
- [The USE Method — Brendan Gregg](https://www.brendangregg.com/usemethod.html)
- [The TSA Method — Brendan Gregg](https://www.brendangregg.com/tsamethod.html)
- [Linux Performance Analysis in 60,000 Milliseconds](https://www.brendangregg.com/Articles/Netflix_Linux_Perf_Analysis_60s.pdf)
- [Off-CPU Analysis](https://www.brendangregg.com/offcpuanalysis.html)
- [Thinking Methodically about Performance (ACM Queue)](https://queue.acm.org/detail.cfm?id=2413037)