obra.

Commenting Intent

Comment WHY code exists and non-obvious decisions, not WHAT code does (mechanics)

Creating Skills

TDD for process documentation - test with subagents before writing, iterate until bulletproof

Designing Before Coding

Design in pseudocode first, iterate approaches, then translate to code

Domain-Focused Naming

Name code by what it does in the domain, not how it's implemented or its history

Encapsulating Complexity

Hide implementation details behind interfaces - work at domain level (what), not implementation level (how)

Exploring Alternatives

Try 2-3 different approaches before implementing - don't settle for first design you think of

Installing Skills System

Fork, clone to ~/.clank, run installer, edit CLAUDE.md

Keeping Routines Focused

Each routine does one thing and does it well - extract when routines have multiple responsibilities

Localizing Variables

Declare variables in smallest possible scope, initialize close to first use, minimize span and live time

Maintaining Consistent Abstractions

Class interfaces present one cohesive abstraction - don't mix domain logic with serialization, persistence, or unrelated concerns

Naming Variables

Choose names that fully and accurately describe what the variable represents

Reducing Complexity

Managing complexity is software's primary technical imperative - all other goals are secondary

Refactoring Safely

Refactor with tests first, one change at a time, never mix refactoring with bug fixes or new features

Simplifying Control Flow

Flatten nested conditionals with early returns or table-driven methods - keep nesting depth under 3 levels

Single Purpose Variables

Use each variable for exactly one purpose - no hybrid coupling or hidden meanings

Validating Inputs

Check all external inputs for validity - garbage in, nothing out, never garbage out

Writing Evergreen Comments

Write comments explaining WHAT and WHY, never temporal context or history

driving-claude-code-sessions

Use when acting as a project manager that delegates tasks to other coding-agent sessions (Claude Code, Codex, or Pi) - launch workers, assign them work, monitor progress, review their tool calls, and collect results

chronicle

|

e2e-scenario-testing

Use when verifying a running application end-to-end through its real interface — a web UI, a CLI, or a TUI — by writing and executing agent-run "scenario cards" against a freshly built instance with falsifiable assertions. Trigger on "test it end to end", "prove the UI actually works", "write/run a scenario", or after a change touches a user-facing surface that unit tests can't fully cover. Not for unit tests, pure code review, or API-only checks.

maintaining-documentation

Use when documentation needs creating, checking, or maintaining — docs may have drifted from code, pre-release doc verification, updating docs after finishing code work, adding or enforcing project terminology, deciding where a new doc should live, or a routine re-audit of previously verified docs.

roborev-design-review

Request a design review for a commit and present the results

roborev-design-review-branch

Request a design review for all commits on the current branch and present the results

roborev-fix

Use when the user asks to fix open failing reviews, invokes /roborev-fix, or provides job IDs; do not use when the user only pastes review findings with no request to discover or close reviews

roborev-refine

Iterative review-fix loop for the current branch — reviews via daemon, fixes inline, re-reviews until passing or max iterations reached

roborev-respond

Add a comment to a roborev code review and close it

roborev-review

Request a code review for a commit and present the results

roborev-review-branch

Request a code review for all commits on the current branch and present the results

syncing-obsidian

Use when reading or writing files in an Obsidian vault that is synced with obsync. Ensures changes are pulled before reading and pushed after writing. Also covers sync status, file history, version restore, and diagnosing sync issues.

maintaining-macos-defaults

Use on demand to reconcile a Mac's GUI-changed settings into version control — when the user says "reconcile my mac defaults", "capture my macOS settings", or after they've changed System Settings and want the keepers tracked. Drives homedir-manager's `defaults` verb (capture/drift/apply) against a versioned desired-state file.

managing-homedir

Use when adding, changing, deploying, onboarding, or auditing homedir-manager content repos — the marker-based symlink deployment system that manages dotfiles and config across your machines. Covers the update workflow, the manifest, OS-splitting, secrets, new-machine onboarding, and the audit process.

prove-claim

Use when asked to prove, disprove, investigate, or find evidence for a claim about people, concepts, ideas, or their relationships. Also use when asked to explore connections, find who influenced what, trace how ideas developed, or answer questions that require reasoning over multiple linked notes.

apple_healthkit

The user's synced Apple Health (HealthKit) data: daily metrics (steps, distance, calories, heart rate, HRV, VO2max), sleep sessions (stages, quality, efficiency), and workouts.

artifact_document

Create, read, edit, or manipulate Word documents (.docx) and Word templates (.dotx). Use whenever a build task's artifact kind is document with the default docx output, or the task mentions a Word doc, .docx, or .dotx, extracts or reorganizes content from one, inserts or replaces images, does find-and-replace in one, or works with tracked changes (redlines) or comments. Covers python-docx generation, raw OOXML editing of existing files, document structure and formatting, and render verification. Not for PDFs, spreadsheets, or Google Docs.

artifact_markdown

Build or revise a plain markdown file (md) deliverable such as notes, a README, meeting minutes, documentation, or text the user will edit or paste elsewhere. Use whenever a build task's artifact kind is markdown. Covers markdown formatting conventions and read-back verification.

artifact_pdf

Build, revise, or manipulate a fixed-layout PDF (report, guide, one-pager, printable document). Use whenever a build task's artifact kind is pdf, a document build's output format is pdf, or the task reads, merges, splits, crops, or fills an existing PDF, including fillable AcroForms. Covers authoring the print-CSS HTML source, rendering, the geometry and validation gates, existing-PDF manipulation and form filling, and delivery under workspace/your_files.

artifact_presentation

Build or revise a slide deck (pptx by default; pdf or html on request). Use whenever a build task's artifact kind is presentation, or the user asks for a deck, slides, or a presentation. Covers per-slide HTML authoring, the StylePlan theme system, font embedding, deck assembly, render gates, and the PPTX export.

artifact_spreadsheet

Create, read, edit, fix, or clean spreadsheet files (.xlsx, .xlsm, .csv, .tsv). Use whenever a build task's artifact kind is spreadsheet, or the task names a spreadsheet file and wants something done to it or produced from it, including restructuring messy tabular data into a proper workbook. Covers openpyxl generation, formulas and recalculation, editing existing workbooks, and the validation gates. Not for tasks whose deliverable is a document, report, or web page that merely contains a table.

artifact_testing

Verify an artifact before delivering it - file deliverables (pdf, pptx, docx, xlsx, csv) and web artifacts alike. Use whenever a build is about to return a link, or a build task asks for validation, QA, or a visual check. Covers the per-kind gate scripts, render-and-look verification, and leftover-placeholder scanning.

asana

>-

booking

Primary entry point for direct flight, hotel, restaurant, or event-ticket transactions and for bounded live availability checks delegated by Travel Planning. Always use before provider-specific skills or browser work when the user asks to find live availability or prices, compare bookable options, book, or continue an active booking. Do not use for trip planning itself, broad inspiration, opening hours, schedules, flight status, or other factual questions without transaction intent.

box

Search, read, upload, download, move, rename, delete, restore, and share Box content; manage comments and metadata.

calendly

View Calendly events and event types, and manage scheduling data using the Calendly CLI.

canva

>-

device_data

Read cached contacts and calendar events from Muse storage. Delete Muse's local copy of either source without modifying paired devices.

dropbox

>-

duffel

Use Duffel to search, book, pay for, or manage flights. Use Duffel to monitor an already booked flight's fare when the user directly asks for ongoing price monitoring.

evernote

Read and create notes through Evernote's official MCP server.

facebook_cli

Use when the user provides a Facebook URL or asks to read personal posts, comments, reactions, friends, timelines, profiles, stories, feeds, groups, events, or saved items, or to publish personal text posts, comments, and replies, or to discover public events happening near a place, nearby, or in a local area on a date, or to create, edit, publish, or delete their own Marketplace listings. To find, browse, or buy Marketplace listings, use shopping instead. Use pages commands for managed Facebook Page discovery, insights, native draft editing/deletion, same-draft publication, approved posts and native scheduling.

figma

>-

flightaware

Use for questions about a specific flight’s departure or arrival time, including “when’s my flight?” and confirmation of remembered times, plus flight status, delays, and cancellations. Verify the exact dated flight before answering; memory identifies the itinerary but does not verify its current schedule. Use FlightAware to monitor operational changes for an upcoming booked flight when the user directly asks for ongoing monitoring.

forget

Remove a personal fact, preference, relationship detail, topic, or prior event from Muse's active memory and stop existing copies or automations from bringing it back. Use for explicit requests such as 'forget that', 'don't remember this about me', or 'remove that from your memory'. Do not use when 'forget it' merely means cancel the current task.

function_health

Retrieve lab biomarker results and clinician notes from Function Health.

generate_podcast

Compose and deliver audio content: a podcast episode, briefing, or narrated summary, with one or more voices, as an MP3. For voice messages, artifact audio, or reading supplied text aloud verbatim, use tts.

ghl

Use HighLevel contacts, pipelines, appointments, messages, and its broader operation catalog.

github

Search and work with the user's GitHub repositories through GitHub's official MCP server.

gmail

Work with the user's Gmail: search, read threads, draft, send, reply, forward, unsubscribe from mailing lists, manage labels, and open attachments.

goals

Guidance for helping users create and accomplish goals. Read it before you create a goal for the user when no goal-creation contract is in context, and whenever you help with an existing goal. A Goals-tab creation turn already carries that contract and does not need this skill.

google_calendar

Work with the user's Google Calendar: agenda views, event details, and scheduling changes.

google_contacts

Search, view, create, update, and delete the user's Google Contacts.

google_docs

Read, create, and edit the user's Google Docs.

google_drive

Work with the user's Google Drive: files, folders, uploads, downloads, and sharing.

google_forms

Read, create, and update the user's Google Forms, and read responses.

google_health_connect

The user's synced Google Health Connect data from their Android device: daily metrics (steps, distance, calories, heart rate, HRV, VO2max), sleep sessions (stages, quality, efficiency), and workouts.

google_sheets

Read, write, and manage the user's Google Sheets.

google_slides

Read, create, and edit the user's Google Slides presentations.

google_tasks

Manage the user's Google Tasks: lists, task details, creation, updates, and completion.

granola

Search and read Granola meeting notes and transcripts through Granola's OAuth-backed MCP server.

healthex

Use to connect HealthEx and ask questions about your medications, lab results, and other health records.

image_search

Search the web by text query for image URLs and source pages for feeds, artifacts, and visual references. Does not identify a supplied image or person.

instagram

Read Instagram profiles, followers, posts, comments, likes, stories, feed, saved content, and account insights. Answer questions about posts, reels, and Instagram links. Manage interests and profile details, and publish stories, reels, posts, or carousels on request.

instagram_messages

Use this to interact with the user's Instagram messages. Read inboxes, threads, top recipients, filtered inbox views, DM search results, and send messages through `instagram-messages-cli`.

klaviyo

>-

lovable

>-

media_library

Search and inspect the user's photo library, including connected device galleries. Use for photo requests and whenever a photo could ground or personalize a response; lookups of uploaded photos are cheap, so check opportunistically and move on if nothing fits.

messenger_read

Work with the user's Messenger account: read call history; read and search contacts; read, search, and summarize conversations; send, react to, unsend, or edit messages; and message Marketplace listing threads.

meta_ads

Create, write, or manage Meta ads and assets: ad copy, campaigns, spend, reports, audiences, catalogs, product feeds, feed refresh schedules, experiments, and policy. Always load for any request to create or write an ad, or to advertise a product or service, even when no platform is named; this includes sensitive or restricted categories. Always load for any question asking what a Meta, Facebook, or Instagram advertising policy means, allows, prohibits, or requires, including a standalone policy-definition question with no account context. Those questions must use ads_policy_tool, never browser search or memory. Load for a specifically named catalog or feed with an upload or refresh-schedule request; use Ads reads to resolve ownership before writing. Generic unnamed feeds need context. Whether an image, claim or piece of copy may be used in an ad is ALWAYS a Meta Ads task — 'can I use this in an ad', 'is it allowed', 'is this against policy', and any rights, likeness, celebrity, logo or trademark question about advertising with an image, including a follow-up about one just generated. Those are ads-policy questions, not general legal ones. An ad request uses the campaign workflow unless explicitly only an image or organic post.

muse_db

Inspect database-backed Muse records for diagnosis and cross-table tracing when purpose-built product tools do not expose the needed state.

muse_early_access

Use for questions about Muse's general early access program, requests to join it, checking or withdrawing a join request, and admission updates.

muse-feedback

Use for feedback and feature requests to the Muse team. Whenever your response tells the user you can't do a specific thing they wanted, or accepts them giving up on one, offer once to file feedback in that response. This covers missing integrations you can't do yourself, capabilities you lack, and tasks that keep failing at a specific point. File only on their go-ahead. Also use when asked to send, view, check, or withdraw feedback.

notion

Search, read, create, and update Notion pages via the Notion MCP.

opentable

Find restaurants on OpenTable, check availability, and make, change, or cancel reservations. Use for restaurant booking and live reservation data.

outlook_calendar

View, create, update, and delete events in the user's Outlook Calendar.

outlook_contacts

List, search, create, update, and delete contacts in the user's Outlook account.

outlook_mail

Read, search, send, reply to, and delete messages in the user's Outlook Mail.

peloton

Connect to Peloton to browse fitness classes, check schedules, and book workouts.

philips_hue

Control Philips Hue smart lights, rooms, scenes, and devices via the Hue Remote API v2.

places_search

Find, compare, and share details on physical places near the user or in a specified area, including restaurants, cafes, bars, hotels, parks, attractions, shops, and businesses with local services. Not for itineraries, choosing a city or region, dated events or showtimes, or directions.

plaid

Use to connect Plaid and read linked financial accounts: metadata, balances, transactions, recurring transactions, liabilities, and investments.

printify

Use Printify to browse catalog data, manage shops and products, and review or create orders.

quickbooks

Read and manage the user's QuickBooks business through Intuit's official MCP server, including reports, invoices, customers, products, payment links, sales settings, and industry benchmarks.

replit

Read, create, update, and publish apps through Replit's official MCP server.

self_awareness

Ground self-referential answers in the agent's actual filesystem. Use when the user asks who the agent is, what it can do, what it knows, what it remembers, what it has built, what services are connected, or what rules it follows.

share_ideas

Publish a reusable native Muse Idea with idea.share when the user explicitly asks to share or publish an Idea or asks for a muse.ai/ideas link. Never offer it unprompted. Not for pages or write-ups, sending a result to someone, social posts, or sharing an artifact.

shopify

>

shopping

Use for any product or shopping question: find, reverse image search, shopping Instagram/Facebook/Marketplace links, buy, compare, or evaluate real products with prices, images, and product page URLs, including buying or browsing Facebook Marketplace listings. Use when presenting shopping search results from any source. For shopping intent, load this skill first before any other skills.

skill_creator

Create or update a workspace skill: its description, structure, instructions, and supporting files.

slack

>-

social_content_performance

Analyze the user's own Instagram account and post performance using linked-account analytics.

spotify

Discover, search, and manage Spotify music, audiobooks, podcasts, and playlists, including deleting shows or episodes you created with Save to Spotify.

stripe

>-

subscription_status

Answer questions about the user's Muse subscription, plan, usage, tokens, reset timing, or available plans and prices, or verify information that references the Muse subscription.

tailscale

Set up Muse's built-in Tailscale connector, join a tailnet or Headscale network, check status, and reach private machines through the TCP tunnel proxy. Read for Tailscale, VPN, MagicDNS, network egress, exit-node, or browser routing questions and supported limits.

tessie

Monitor a Tesla vehicle, inspect live state, and run explicit Tessie command endpoints.

threads

Read and manage the user's Threads account: profile, posts, feed, saved posts, activity, insights, social graph, search, trends, and a specific post by URL or ID. Can tune feed ranking and publish posts on request.

threads_messages

Use this to interact with the user's Threads messages: read inboxes and message threads, and send messages through `threads-messages-cli`.

ticketmaster

Search Ticketmaster events and seats with pricing. Returns Buy-now links to Ticketmaster checkout; it cannot complete a purchase itself.

todoist

Read and manage Todoist tasks, projects, comments, labels, filters, and reminders through Todoist's official MCP server.

travel_planning

Use this skill when an active or proposed trip needs planning, logistics, feasibility, entry or transit checks, itinerary work, or investigation of an airport process, immigration, ground transport, a transfer, or fast-track service, even for a narrow question with no booking intent. Route a bounded flight, hotel, restaurant, event, or other item ready for live availability or booking directly to Booking. Skip this skill for a stable travel fact alone or flight status.

tts

Generate spoken audio from text, single or multi-speaker, including voice notes or messages for chat, audio for artifacts, and audio from cron jobs. For podcasts, briefings, or narrated summaries, use podcast.

vercel

>-

voice_selector

Provides the static system voice catalog used by Jarvis. It does not define a user-facing workflow.

wearables_comms

>-

wide_research

Use when the user needs broad parallel research across many independent inputs with a shared output schema.

withings

Use when linking Withings or reading Withings body measurements, activity, sleep, workout, heart, and intraday data.

zapier

Connect Muse to actions across apps through Zapier's official MCP server.

zoom

>-

blender-reconstruct

Build and review evidence tagged Blender architectural candidates, preserve unrelated scene content, and produce requested photographic materials, stills and portable model deliveries.

depth-inspect

Inspect native RGB, depth, confidence, calibration, and poses to make finite, source traceable reference points and surface measurements.

scan-ingest

Preserve and inventory scan archives while retaining capture variants, hashes, calibration, and frame provenance.

scan-register

Fit and independently validate rigid scan alignment from named, source traceable correspondences.

scan-to-model

Coordinate evidence based reconstruction from scans, photos, plans, and measurements into a reviewable Blender architectural model, with photographic appearance, renders and portable browser delivery when requested.

source-observe

Use when cataloging or annotating visible construction in photographs or scan RGB, especially before registration or while the base model may be replaced.

street-view-reference

Collect and verify Google Street View exterior references for a building reconstruction, preserving panorama identity, imagery dates, attribution and viewpoint separately from calibrated scan evidence.

linear

Manage Linear issues. Use when asked about tasks, tickets, bugs, or Linear.

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).

diagnosing-superpowers

Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.

dispatching-parallel-agents

Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies

executing-plans

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

finishing-a-development-branch

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work

receiving-code-review

Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

subagent-driven-development

Use when executing implementation plans with independent tasks in the current session

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

using-git-worktrees

Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback

using-superpowers

Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions

verification-before-completion

Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always

writing-plans

Use when you have a spec or requirements for a multi-step task, before touching code

writing-skills

Use when creating new skills, editing existing skills, or verifying skills work before deployment

browsing

Use when you need direct browser control - teaches Chrome DevTools Protocol for controlling existing browser sessions, multi-tab management, form automation, and content extraction via use_browser MCP tool

developing-claude-code-plugins

Use when working on Claude Code plugins (creating, modifying, testing, releasing, or maintaining) - provides streamlined workflows, patterns, and examples for the complete plugin lifecycle

example-workflow

Use when demonstrating plugin workflow features - shows how skills can guide multi-step processes

working-with-claude-code

Use when working with Claude Code CLI, plugins, hooks, MCP servers, skills, configuration, or any Claude Code feature - provides comprehensive official documentation for all aspects of Claude Code

finding-duplicate-functions

Use when auditing a codebase for semantic duplication - functions that do the same thing but have different names or implementations. Especially useful for LLM-generated codebases where new functions are often created rather than reusing existing ones.

mcp-cli

Use MCP servers on-demand via the mcp CLI tool - discover tools, resources, and prompts without polluting context with pre-loaded MCP integrations

using-tmux-for-interactive-commands

Use when you need to run interactive CLI tools (vim, git rebase -i, Python REPL, etc.) that require real-time input/output - provides tmux-based approach for controlling interactive sessions through detached sessions and send-keys

windows-vm

Create, manage, or connect to a headless Windows 11 VM running in Docker with SSH access. Use when the user wants to spin up, stop, restart, or SSH into a Windows VM.

Brainstorming Ideas Into Designs

Interactive idea refinement using Socratic method to develop fully-formed designs

Code Review Reception

Receive and act on code review feedback with technical rigor, not performative agreement or blind implementation

Collision-Zone Thinking

Force unrelated concepts together to discover emergent properties - "What if we treated X like Y?"

Condition-Based Waiting

Replace arbitrary timeouts with condition polling for reliable async tests

Defense-in-Depth Validation

Validate at every layer data passes through to make bugs impossible

Gardening Skills Wiki

Maintain skills wiki health - check links, naming, cross-references, and coverage

Getting Started with Skills

Skills wiki intro - mandatory workflows, search tool, brainstorming triggers

Inversion Exercise

Flip core assumptions to reveal hidden constraints and alternative approaches - "what if the opposite were true?"

Meta-Pattern Recognition

Spot patterns appearing in 3+ domains to find universal principles

Preserving Productive Tensions

Recognize when disagreements reveal valuable context, preserve multiple valid approaches instead of forcing premature resolution

Pulling Updates from Skills Repository

Sync local skills repository with upstream changes from obra/superpowers-skills

Remembering Conversations

Search previous Claude Code conversations for facts, patterns, decisions, and context using semantic or text search

Root Cause Tracing

Systematically trace bugs backward through call stack to find original trigger

Scale Game

Test at extremes (1000x bigger/smaller, instant/year-long) to expose fundamental truths hidden at normal scales

Sharing Skills

Contribute skills back to upstream via branch and PR

Simplification Cascades

Find one insight that eliminates multiple components - "if this is true, we don't need X, Y, or Z"

Test-Driven Development (TDD)

Write the test first, watch it fail, write minimal code to pass

Testing Anti-Patterns

Never test mock behavior. Never add test-only methods to production classes. Understand dependencies before mocking.

Testing Skills With Subagents

RED-GREEN-REFACTOR for process documentation - baseline without skill, write addressing failures, iterate closing loopholes

Tracing Knowledge Lineages

Understand how ideas evolved over time to find old solutions for new problems and avoid repeating past failures

When Stuck - Problem-Solving Dispatch

Dispatch to the right problem-solving technique based on how you're stuck

writing-clearly-and-concisely

Apply Strunk's timeless writing rules to ANY prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Makes your writing clearer, stronger, and more professional.