Claude Skills by marcioaltoe

Design principles for building CLI tools that LLM/AI agents can safely and reliably operate. Provides 7 core principles (Machine-readable, Non-interactive, Idempotent, Safe-by-default, Observable, Context-efficient, Introspectable) with scorecard, templates, and anti-patterns. Use when: (1) designing new CLI tools for agent use, (2) improving existing CLIs for agent compatibility, (3) reviewing CLI design for agent-friendliness, or (4) need guidance on JSON output formats, exit codes, authent...

Archive a completed spec — verify every task completed, QA passed, and indexed references are self-contained, then stamp the archive metadata and move <spec-root>/<slug>/ to the resolved archive root (<spec-root>/_archived/<slug>/, or docs/history/specs/<slug>/ for the built-in docs/specs root). Runs automatically at the end of the implement-spec loop after a QA pass, or whenever the user asks to archive a spec.

Autonomously optimize any Claude Code skill by running it repeatedly, scoring outputs against binary evals, mutating the prompt, and keeping improvements. Based on Karpathy's autoresearch methodology. Use when: optimize this skill, improve this skill, run autoresearch on, make this skill better, self-improve skill, benchmark skill, eval my skill, run evals on. Outputs: an improved SKILL.md, a results log, and a changelog of every mutation tried.

You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design through one question at a time, then routes the outcome to write-idea, write-prd, write-techspec (refactors/bug fixes), or a direct task.

Build terminal user interfaces with Go and Bubbletea framework. Use when creating TUI apps with the Elm architecture, dual-pane layouts, accordion modes, mouse/keyboard handling, Lipgloss styling, and reusable components. Includes production-ready templates and battle-tested layout patterns from real projects. Don't use for plain-text CLI scripts without an interactive UI, web/desktop GUIs, or non-Go terminal frameworks (Ink, Textual, Ratatui).

Turns exploration into decision-ready analysis: scores feature ideas on six viability criteria with KPI targets, converts open questions into A/B/C options with a recommended default, and produces executive-grade deliverables (KPI frameworks, forecasts, cohort/LTV-CAC models, A/B readouts, market sizing). Use during idea/PRD discovery to score or structure a decision, and whenever the task is quantitative decision support. Don't use for software implementation, UI work, or database migration.

Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, modifying, or reviewing code — implementation tasks, code changes, refactoring, bug fixes, or feature development. Do NOT use for architecture design, documentation, or non-code tasks.

Create Conventional Commits and PR titles that pass Cocogitto validation. Use when the user asks to commit, stage changes, split commits, write a commit message, open or update a PR title, or prepare squash-merge history.

Orchestrates multi-advisor council debates on high-impact architecture, technology, or product decisions. Dispatches 3-5 domain archetype subagents (pragmatic-engineer, architect-advisor, security-advocate, product-mind, devils-advocate, the-thinker) through opening statements, tensions, position evolution, and synthesis phases. Preserves dissent and delivers actionable recommendations with captured risks. Use when evaluating trade-offs, stress-testing a PRD or tech spec, resolving dilemmas w...

Require fresh verification evidence before claiming work is complete, fixed, passing, committed, PR-ready, or ready for handoff. Use before completion claims, commits, pushes, PR creation, issue status changes, delivery summaries, or agent handoffs; do not use for brainstorming or planning that makes no delivery claim.

Deep research powered by Exa. Use for lead generation, literature reviews, deep dives, competitive analysis, or any query where one search falls short, including phrases like 'research this', 'find everything about', 'find me all', or 'deep dive on'.

Golang CLI application development. Use when building, modifying, or reviewing a Go CLI tool — especially for command structure, flag handling, configuration layering, version embedding, exit codes, I/O patterns, signal handling, shell completion, argument validation, and CLI unit testing. Also triggers when code uses cobra, viper, or urfave/cli. For cobra-specific APIs → See `samber/cc-skills-golang@golang-spf13-cobra` skill; for viper configuration layering → See `samber/cc-skills-golang@go...

Golang concurrency patterns. Use when writing or reviewing concurrent Go code involving goroutines, channels, select, locks, sync primitives, errgroup, singleflight, worker pools, or fan-out/fan-in pipelines. Also triggers when you detect goroutine leaks, race conditions, channel ownership issues, or need to choose between channels and mutexes.

Idiomatic context.Context usage in Golang — propagation through API boundaries, cancellation, timeouts and deadlines, request-scoped values, context.WithoutCancel for background work outliving requests. Apply when designing context propagation across layers, debugging leaked or unexpired contexts, choosing between context.Background/TODO/WithoutCancel, or storing values in context. Not for code that merely accepts ctx as first parameter.

Dependency management strategies for Golang projects — go.mod management, installing/upgrading packages, Minimal Version Selection, vulnerability scanning, outdated dependency tracking, binary size analysis, Dependabot/Renovate setup, conflict resolution, and go.work workspaces. Use when adding, removing, or upgrading Go dependencies, auditing vulnerabilities, resolving version conflicts, or setting up automated dependency updates.

Idiomatic Golang error handling — creation, wrapping with %w, errors.Is/As, errors.Join, custom error types, sentinel errors, panic/recover, the single handling rule, structured logging with slog, HTTP request logging middleware, and samber/oops for production errors. Built to make logs usable at scale with log aggregation 3rd-party tools. Apply when creating, wrapping, inspecting, or logging errors in Go code. For samber/oops specifics → See `samber/cc-skills-golang@golang-samber-oops` skill...

Linting best practices and golangci-lint configuration for Golang projects — running linters, configuring .golangci.yml, suppressing warnings with nolint directives, interpreting lint output, and selecting linters. Use when configuring golangci-lint, asking about lint warnings or nolint suppressions, setting up code quality tooling, or choosing linters. Also use when the user mentions golangci-lint, go vet, staticcheck, or revive.

Defensive Golang coding to prevent panics, silent data corruption, and subtle runtime bugs. Use when encountering nil panics, append aliasing, map concurrent access, float comparison pitfalls, or zero-value design questions. Also use when reviewing code for nil-safety, numeric conversion overflow, resource lifecycle issues (defer in loops), or defensive copying of slices and maps.

Golang struct and interface design patterns — composition, embedding, type assertions, type switches, interface segregation, dependency injection via interfaces, struct field tags, and pointer vs value receivers. Use this skill when designing Go types, defining or implementing interfaces, embedding structs or interfaces, writing type assertions or type switches, adding struct field tags for JSON/YAML/DB serialization, or choosing between pointer and value receivers. Also use when the user ask...

Production-ready Golang tests — table-driven tests, testify suites and mocks, parallel tests, fuzzing, fixtures, goroutine leak detection with goleak, snapshot testing, code coverage, integration tests, idiomatic test naming. Use when writing or reviewing Go tests, choosing a testing approach, setting up Go test CI, or debugging flaky/slow tests. For testify-specific APIs see `samber/cc-skills-golang@golang-stretchr-testify`; for measurement methodology see `samber/cc-skills-golang@golang-ben...

Implement every pending task of a spec in dependency order — resolve the _tasks.md graph into waves and run the implement-task cycle per task, starting immediately on invocation with no confirmation prompts, and finish by running the qa-gate against the whole feature.

Execute one task file from docs/specs/<slug>/ end-to-end — ground in the PRD/TechSpec, implement only the slice, and hand back evidence under the execution mode's settlement contract. Starts immediately when assigned, with no confirmation prompt. Use when the user says "run task_03", "execute the next task", "pick up a task", or when an implementation loop or daemon assigns a task file from a spec folder.

Work with project documentation and the central knowledge repository (marcioaltoe/secondbrain). Use when editing docs/, CONTEXT.md, specs, ADRs, or task files in any repo with a .secondbrain-project file; when deciding where a documentation change should be committed; when touching secondbrain's mirror, notes, shared or wiki areas; and when research, planning or implementation work could consult or feed the second brain (wiki + qmd search).

Fix problems at their root cause instead of patching symptoms. Use when debugging, fixing bugs, resolving test failures, planning a solution, or reviewing a change — especially where a fix would silence a signal (type assertion, lint suppression, swallowed error, timing hack, monkey patch) rather than repair its source. Not for formatting- or docs-only edits.

Execute the self-contained final QA gate as a Spec's authored terminal `qa` Task — derive a resumable QA matrix from the PRD and task evidence, execute real user flows through every declared surface, probe high-risk user behavior, capture auditable evidence, classify findings by user impact, and write the spec-local dated QA report. Do not use as a substitute for implementation tests or a broad standalone QA knowledge base.

Use Roundfix to plan releases with the read-only Release Plan Command, clean CodeRabbit pull request feedback, diagnose runtime readiness with the Doctor Command, execute a Spec's Task Graph with the Implement Command, monitor Runs through the Supervisor Run Event Stream, reclaim Run storage with the GC Command, archive completed Specs, and, inside daemon-assigned Batch runs, follow the bounded Review Issue or Task resolution contract.

Adopt, update, or verify a repository's Context-Driven Baseline through the public Roundfix Baseline Command. Use when preparing a repository for the write-prd/write-tasks/implement pipeline, changing its Baseline Profile, preserving existing instructions, restoring its Repository Skill Set, or confirming that Baseline-owned content is current.

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

Write or rewrite anything technical people write — READMEs, documentation pages, quickstarts, PRDs, tech specs, RFCs, ADRs, design docs, task breakdowns and task files, GitHub issues, bug reports, QA test plans, test cases, exploratory charters, verification reports, PR descriptions, code review comments, and async team updates — so it reads clearly, scans fast, stays faithful to source facts, and sounds human. Use when the user says "write a README", "improve these docs", "write a PRD", "wri...

Use when challenging ideas, plans, decisions, or proposals. Invoke to play devil's advocate, run a pre-mortem, red team, stress test assumptions, audit evidence quality, or find blind spots before committing. Do NOT use for building plans, making decisions, or generating solutions — this skill only challenges and critiques.

This skill should be used when designing terminal user interfaces, creating TUI layouts, choosing TUI color schemes, implementing keyboard navigation, building terminal dashboards, or working with any TUI framework. Activates on mentions of TUI design, terminal UI, Ratatui layout, Ink components, Textual widgets, Bubbletea views, terminal color palette, keybinding design, panel layout, split panes, terminal dashboard, box-drawing characters, sparklines, progress bars, modal dialogs, focus man...

Expand a raw product idea into a research-backed spec at docs/specs/<slug>/_idea.md — targeted questions, parallel codebase + market research, business-viability scoring, council debate, and an opportunity scan before drafting. The _idea.md feeds write-prd.

Write a PRD as a durable local artifact at docs/specs/<slug>/_prd.md — research first, clarify with one multiple-choice question at a time, record decisions as ADRs, then write directly without draft-approval rounds.

Decompose a spec's PRD/TechSpec into a dependency-ordered task graph — vertical-slice task files plus a machine-parseable _tasks.md DAG manifest under docs/specs/<slug>/, including the authored QA gate decision, decided autonomously from the Spec and escalated only when authority, architecture, or blast radius is at stake.

Write the technical spec at docs/specs/<slug>/_techspec.md — explore the architecture, settle technical decisions one question at a time, record them as ADRs, and produce a build order that write-tasks can decompose. Entry point for feature work with an approved PRD, and also for refactors and bug fixes, where it mints the spec folder with a minimal _prd.md instead of requiring a product interview.

Archive a completed spec — verify every task completed, QA passed, and indexed references are self-contained, then stamp the archive metadata and move <spec-root>/<slug>/ to the resolved archive root (<spec-root>/_archived/<slug>/, or docs/history/specs/<slug>/ for the built-in docs/specs root). Runs automatically at the end of the implement-spec loop after a QA pass, or whenever the user asks to archive a spec.

You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design through one question at a time, then routes the outcome to write-idea, write-prd, write-techspec (refactors/bug fixes), or a direct task.

Turns exploration into decision-ready analysis: scores feature ideas on six viability criteria with KPI targets, converts open questions into A/B/C options with a recommended default, and produces executive-grade deliverables (KPI frameworks, forecasts, cohort/LTV-CAC models, A/B readouts, market sizing). Use during idea/PRD discovery to score or structure a decision, and whenever the task is quantitative decision support. Don't use for software implementation, UI work, or database migration.

Orchestrates multi-advisor council debates on high-impact architecture, technology, or product decisions. Dispatches 3-5 domain archetype subagents (pragmatic-engineer, architect-advisor, security-advocate, product-mind, devils-advocate, the-thinker) through opening statements, tensions, position evolution, and synthesis phases. Preserves dissent and delivers actionable recommendations with captured risks. Use when evaluating trade-offs, stress-testing a PRD or tech spec, resolving dilemmas w...

Require fresh verification evidence before claiming work is complete, fixed, passing, committed, PR-ready, or ready for handoff. Use before completion claims, commits, pushes, PR creation, issue status changes, delivery summaries, or agent handoffs; do not use for brainstorming or planning that makes no delivery claim.

Implement every pending task of a spec in dependency order — resolve the _tasks.md graph into waves and run the implement-task cycle per task, starting immediately on invocation with no confirmation prompts, and finish by running the qa-gate against the whole feature.

Execute one task file from docs/specs/<slug>/ end-to-end — ground in the PRD/TechSpec, implement only the slice, and hand back evidence under the execution mode's settlement contract. Starts immediately when assigned, with no confirmation prompt. Use when the user says "run task_03", "execute the next task", "pick up a task", or when an implementation loop or daemon assigns a task file from a spec folder.

Execute the self-contained final QA gate as a Spec's authored terminal `qa` Task — derive a resumable QA matrix from the PRD and task evidence, execute real user flows through every declared surface, probe high-risk user behavior, capture auditable evidence, classify findings by user impact, and write the spec-local dated QA report. Do not use as a substitute for implementation tests or a broad standalone QA knowledge base.

Use Roundfix to plan releases with the read-only Release Plan Command, clean CodeRabbit pull request feedback, diagnose runtime readiness with the Doctor Command, execute a Spec's Task Graph with the Implement Command, monitor Runs through the Supervisor Run Event Stream, reclaim Run storage with the GC Command, archive completed Specs, and, inside daemon-assigned Batch runs, follow the bounded Review Issue or Task resolution contract.

Adopt, update, or verify a repository's Context-Driven Baseline through the public Roundfix Baseline Command. Use when preparing a repository for the write-prd/write-tasks/implement pipeline, changing its Baseline Profile, preserving existing instructions, restoring its Repository Skill Set, or confirming that Baseline-owned content is current.

Expand a raw product idea into a research-backed spec at docs/specs/<slug>/_idea.md — targeted questions, parallel codebase + market research, business-viability scoring, council debate, and an opportunity scan before drafting. The _idea.md feeds write-prd.

Write a PRD as a durable local artifact at docs/specs/<slug>/_prd.md — research first, clarify with one multiple-choice question at a time, record decisions as ADRs, then write directly without draft-approval rounds.

Decompose a spec's PRD/TechSpec into a dependency-ordered task graph — vertical-slice task files plus a machine-parseable _tasks.md DAG manifest under docs/specs/<slug>/, including the authored QA gate decision, decided autonomously from the Spec and escalated only when authority, architecture, or blast radius is at stake.

Write the technical spec at docs/specs/<slug>/_techspec.md — explore the architecture, settle technical decisions one question at a time, record them as ADRs, and produce a build order that write-tasks can decompose. Entry point for feature work with an approved PRD, and also for refactors and bug fixes, where it mints the spec folder with a minimal _prd.md instead of requiring a product interview.