dotfiles

Write or rewrite text in ASD-STE100 Simplified Technical English (STE): the approved-word dictionary discipline, controlled verb forms, sentence and paragraph limits, procedural vs descriptive rules, and safety-instruction structure. Use when the user asks for Simplified Technical English, STE, ASD-STE100, controlled language, or aerospace-style technical writing, or when authoring procedures, maintenance instructions, or safety warnings that must be unambiguous. Do NOT use for general documentation cleanup (use clean-docs), README structure (use write-readme), or ordinary prose style.

House doctrine for designing LLM agent systems: safety enforced by the harness and tools rather than model goodwill, tools that execute and return results, minimal loop code, interface-first component seams, typed config, deterministic evals over LLM judges, and POC scope discipline. Use when designing or reviewing any agent, tool-use loop, eval harness, or agent-backed CLI, in any framework. Do NOT use for Pydantic AI framework mechanics (use building-pydantic-ai-agents), generic design principles (use review-design), or Go agent-loop implementation details (use agent).

Operate the detect-secrets pre-commit hook correctly: update the baseline with the right flags, break the "baseline file was updated, please git add" commit loop, allowlist false positives, and audit real findings. Use when a commit fails on detect-secrets, the .secrets.baseline keeps changing, or a false positive blocks a push. Do NOT use for storing or injecting secrets via 1Password (use manage-secrets) or repo-wide leak scanning with gitleaks and trufflehog (use audit-security).

Run a project's own eval suite end to end without babysitting: locate the harness, launch it in the background, monitor to completion, parse the report into a normalized summary (pass rate, latency percentiles, tokens, cost), and diff against the previous run with per-case regressions explained. Use when asked to "run the evals", re-run after a change, or score a new dataset in any repo with an eval harness. Do NOT use for the GAP benchmark suite (use run-evals), SAIGE provider-boundary checks (use verify), or designing new eval sets (that is authoring work, not a run).

Playbook of known failure modes in this dotfiles stack: pipx "bad interpreter" after Python rebuilds, gpg commit-signing failures, direnv/nix shellHook running bash instead of zsh, Powerlevel10k instant-prompt warnings, and Neovim plugin errors from removed Lua APIs. Use when a shell startup error, git signing failure, broken CLI shim, or nvim stack trace appears on this machine. Do NOT use for generic runtime debugging in projects (use diagnose-runtime), chezmoi naming and templating conventions (use dotfiles), or authoring pinned installers (use setup-devenv-with-chezmoi).

Clean and modernize documentation in place. Enforce no em dashes, readable structure, proper Markdown formatting, accurate commands, current examples, resolved internal links, and user-focused guidance. Use when the user invokes /clean-docs, asks to clean docs, make docs up to date, improve README/AGENTS prose, remove AI-looking punctuation, or make docs easier for users to act on.

Create well-formed Agent Skills following the agentskills.io specification. Scaffold directories, write SKILL.md files, bundle scripts, and structure instructions for progressive disclosure. Use when creating a new skill, reviewing skill structure, optimizing a skill description, or setting up evals for skill quality.

Chezmoi dotfiles conventions and patterns. Use when modifying dotfiles, adding new managed files, working with chezmoi templates, or syncing agent skills and subagents through agentspec.

Orchestrate multiple agent CLIs (Claude, Codex, Antigravity) via tmux with a shared fleet store, dispatching one guardian subagent per pane. Survey-first: inspects and adopts existing tmux sessions, windows, and agent panes before creating anything new. Use when running a multi-agent session, dispatching parallel work, or coordinating subagents across panes.

Audit and synchronize project documentation. Enforce clean prose, no em dashes, evidence-backed accuracy, current embedded examples, command drift checks, and cross-reference consistency. Use after feature changes, refactors, stale docs, README/AGENTS/llms.txt edits, or when the user asks to clean up docs. Delegates file-specific structure to owning skills.

Structures and writes a project README: centered header, badges, demo image, section order, install.sh one-liner, Quick Start, fsrc code embeds, and the Agent Skill section. Use when creating or updating any project's README.md. Do NOT use for AGENTS.md or the skills-vs-docs taxonomy -> use configure-ai (configure-ai owns AGENTS.md and the docs taxonomy; write-readme owns README structure). For llms.txt generation -> use create-llms-txt.

Create, enter, and clean up git worktrees under the mandatory layout: every worktree lives at <repo-root>/.worktrees/<name> in the target repo's primary checkout, .worktrees/ is always gitignored, and the primary checkout never leaves the default branch. Use when creating a worktree, working on parallel branches, isolating an agent's edits, or when the user says "worktree", "work in parallel", or "branch without switching". Do NOT use for commit/PR/merge flow (use ship, pr, merge-ready) or for plain single branch work that needs no isolation.

Drive an existing pull request to a mergeable state: get CI green, resolve merge conflicts with the base branch, address and resolve review comments, trigger required bot reviews/approvals (e.g. commenting '@claude review'), link associated issues, and clean up the PR title and description. Ends with a readiness report listing any remaining human-only blockers (required reviewer approvals, CODEOWNERS). Uses the CLI matching the repo's forge: gh for GitHub, glab for GitLab merge requests, tea for Gitea/Forgejo. Use when the user says "get this PR ready to merge", "make this PR mergeable", "get the PR green", "address the review comments", "babysit this PR", "get this MR merged", or "why is this PR blocked". Do NOT merge the PR or enable auto-merge; do NOT open a new PR (use pr); do NOT use for a failing pipeline with no PR context (use fix-and-retry / diagnose-ci).

Authors AGENTS.md and defines the skills-vs-docs boundary for a repo. Configures AI coding tools (Claude Code, Codex, Antigravity CLI, Copilot) and the skills-as-docs philosophy. Use when creating or auditing AGENTS.md, setting up AI tooling for a project, or deciding what belongs in a skill versus docs/. Do NOT use for README structure -> use write-readme; for llms.txt generation -> use create-llms-txt; for Claude-specific skill features (invocation control, subagents, model overrides) -> use extend-oss-skills-to-claude.

Foundational quality framework: the five questions (readable, easy to start, expands without bloat, consistent, intentional) every other dev skill is judged against, plus the dual-audience and workshop principles. Use when onboarding to a project, defining a quality bar, setting an assessment checklist, or arbitrating between review-design and write-code. Do NOT use for the design "why" layer (use review-design) or concrete tool/pattern picks (use write-code). For day-to-day "review my staged/unstaged changes" asks, use review-diff instead.

Scans a repo and host for leaked keys and secrets (gitleaks, trufflehog), audits SSH/GPG/.env file permissions, checks git hygiene, investigates suspicious processes and listeners, and hardens config (FileVault, firewall, SIP, SSH). Use when auditing for leaked credentials or secrets, checking for security issues before a commit, investigating an unknown process or open port, or hardening a machine. Do NOT use for storing, injecting, or rotating secrets at rest (1Password, op read, vaults) -> use manage-secrets; this skill only detects and reports exposure.

Design and audit CLI tools end-to-end: output modes, TTY detection, JSON piping, stderr/stdout separation, color/symbol semantics, the ui module pattern, signal handling, exit codes, and install.sh. Use when building, reviewing, or releasing any CLI and you need general CLI design guidance. Do NOT use for the mandatory urmzd/* portfolio CLI rules (argument-parser choice, self-update requirement, --format flag, global flags, install.sh template): cli-standards owns those and overrides this skill where they conflict.

Validate project structure against scaffold conventions -- check for required files, CI consistency, documentation completeness, sub-package/workspace members, and optional directory usage, reporting PASS/WARN/FAIL with fix suggestions. Use to audit an existing project or verify a scaffold was applied correctly. Do NOT use to create or modify project files; this is a read-only auditor (use the scaffold-* skills to generate structure).

Canonical tech-stack reference organized by purpose: release/versioning (sr), docs/demos (teasr, fsrc), codegen (oag), and per-language tools (cargo, clippy, clap, golangci-lint, biome, tsdown, uv, ruff, ty, pytest, pydantic, fastapi). Use when choosing a library, picking the standard CLI/linter/logging tool for a language, setting up a project, or asking "what do we use for X." Do NOT use for coding patterns or error-handling idioms (use write-code) or testing frameworks in depth (use test-code).

Scaffold the GitHub Community Standards files (CODE_OF_CONDUCT, SECURITY, ISSUE_TEMPLATE, pull_request_template) using $COMMUNITY_HEALTH_CONTACT or git config user.email as the contact. Use when bootstrapping a new repo or backfilling community-health coverage.

Generate a spec-compliant llms.txt file for any project by analyzing its codebase, docs, and public URLs. Use when creating an llms.txt, making a project LLM-discoverable, or when the user mentions "llms.txt" in the context of generating or scaffolding one.

Investigate failing REMOTE CI runs on GitHub Actions: find the failed run, pull the failed-step logs with gh, identify the root cause (compile error, test failure, lint, missing secret, timeout), and recommend a fix. Read-only: it does not commit, push, or edit. Use when CI is red, a GitHub Actions run failed, or the user asks "why did the pipeline fail". Do NOT use for local build/test/runtime failures on your machine (use diagnose-runtime); do NOT apply the fix and re-ship (use fix-and-retry) -- this skill investigates and recommends only.

Triage LOCAL runtime failures on your own machine: crashes and errors, hangs and deadlocks, slowness and high CPU/memory, and hardware/serial/USB issues. Method: reproduce, isolate (bisect, log, strace/dtruss, sample), form a hypothesis, verify the fix holds. Read-mostly: it inspects processes and logs, it does not commit, push, or edit source. Use when the user asks "why does this error", "why does the system hang after generating the PDF", "why is the computer running hot", "why is image loading slow", or "this process is stuck". Do NOT use for CI/pipeline failures (use diagnose-ci) or for applying and re-shipping a fix (use fix-and-retry) -- this skill investigates and recommends only.

Extend standard agentskills.io skills with Claude Code-specific features. Invocation control, subagent execution, dynamic context injection, string substitutions, model/effort overrides, and deployment scoping. Use when adapting a portable skill for Claude Code, adding Claude-specific frontmatter, setting up subagent delegation, or configuring skill permissions.

Diagnose a failing CI run, apply the code fix, commit it, push, and watch the re-run until it passes or fails -- the full fix-and-retry loop in one shot. Use after a pipeline fails and the user says "fix it and retry", "fix the CI and push", or "make CI green". Do NOT use for a read-only investigation that stops at a recommendation (use diagnose-ci); do NOT use for a routine commit unrelated to a CI failure (use ship).

1Password-based secret storage workflow: vault layout, 1p:// references in .envrc, op run for local execution. Use when storing or rotating credentials with 1Password. (Other backends not covered.)

Open a pull request via gh pr create with an auto-generated title and summary derived from the commits on the branch, grouped by conventional-commit type. Use when the user says "create a pull request", "open a PR", "gh pr create", "raise a PR", or "make a PR for this branch". Assumes commits already exist and only opens the PR. Do NOT commit changes or watch CI (use ship); do NOT diagnose or fix a failing pipeline (use fix-and-retry / diagnose-ci).

Audit GitHub releases, git tags, and release assets for one repo or every repo in a directory. Flags orphaned tags, missing binaries/checksums, draft releases, floating tag drift, pre-release remnants, and (when sr.yaml is present) sr config issues. Read-only: never deletes or modifies tags/releases. Use when checking "release health", "orphaned tags", "missing assets", "draft releases stuck", or "is sr.yaml configured right". Do NOT use to cut or publish a release, and do NOT use to set up the release pipeline -- this only audits and reports.

End-to-end repo bootstrap: creates the GitHub repo (gh repo create), adds an Apache-2.0 LICENSE, dispatches to scaffold-project for CI/release/config, invokes community-health, writes a README, sets topics/description, and makes the initial commit and push. Use when starting a brand-new project from zero and you need the GitHub repo, metadata, and first push handled, not just local files. Do NOT use to scaffold files inside an existing repo; invoke scaffold-project directly for that.

Scan a folder of git repos and report each repo's local dirty/clean state, ahead/behind divergence from upstream, recent activity, and latest CI run status. Read-only: never commits, pushes, or edits. Defaults to the folder argument or your repo root. Use when checking "what's live", "which repos are dirty", or "repo status across my projects". Sibling skills overlap on folder scanning: do NOT use for "what should I work on next" prioritization (use get-work); do NOT use for a recent-activity-only overview without dirty/CI detail (use status). repo-status is the local dirty/ahead/behind + CI-state report.

Pragmatic Programmer principles: DRY, orthogonality, ETC, reversibility, tracer bullets, design by contract, decoupling/Law of Demeter, pragmatic paranoia. The 'why' layer between assess-quality (framework) and write-code (operational). Use when reasoning about design tradeoffs, coupling, or whether a decision is reversible. Do NOT use for the underlying quality framework (use assess-quality) or for concrete tool/idiom/library picks (use write-code).

Standardized review of the CURRENT working-tree changes -- staged, unstaged, and untracked -- against an explicit five-dimension rubric (correctness, security, tests, scope-creep, conventions). Emits a prioritized findings list, each with file:line, severity, and a suggested fix. Read-only: it reviews and reports, it does not commit, push, or edit. Use when the user says "review my changes", "review the diff", "look over my staged changes before I commit", or "what's wrong with this PR locally". Do NOT use for red CI/pipeline failures (use diagnose-ci) or whole-repo quality-framework questions (use assess-quality); this reviews the working-tree diff only. assess-quality and review-design both EXCLUDE day-to-day review and name this skill as its home.

Scaffold a complete Go project with CI/CD, release pipeline, Makefile, sr.yaml, .envrc, and standard files. Uses go toolchain and make as the native build system. Loads on top of scaffold-project (run that first for cross-language standard files). Use when creating a new Go CLI, service, or module, or when the user mentions "new Go project", "go mod init", or "Go scaffold". Do NOT use for Rust, Python, Node, or Terraform projects; use the matching scaffold-<lang> skill.

Scaffold a complete Node/TypeScript project with CI/CD, release pipeline, sr.yaml, .envrc, and standard files. Uses pnpm and biome. Loads on top of scaffold-project (run that first for cross-language standard files). Use when creating a new Node.js app, TypeScript library, or website, or when the user mentions "new Node project", "pnpm init", "TypeScript scaffold", or "Astro site". Do NOT use for Go, Rust, Python, or Terraform projects; use the matching scaffold-<lang> skill.

Generates cross-language standard files (README, AGENTS.md, LICENSE, CONTRIBUTING.md, SECURITY.md, sr.yaml, .envrc, llms.txt), documentation conventions, and project structure, then dispatches to language-specific scaffolds. Use first for cross-language standard files and structure, THEN load the matching scaffold-<lang> skill (scaffold-rust, scaffold-go, scaffold-python, scaffold-node, scaffold-terraform) for CI/CD, release pipelines, and tooling. Use when creating or standardizing projects. Do NOT use alone for a single-language project; co-load the matching scaffold-<lang> skill for its CI/CD and tooling.

Scaffold a complete Python project with CI/CD, release pipeline, justfile, sr.yaml, pyproject.toml, .envrc, and standard files. Uses uv, ruff, and justfile (Python lacks a native task runner like pnpm scripts, so just fills that gap). Loads on top of scaffold-project (run that first for cross-language standard files). Use when creating a new Python CLI, library, or application, or when the user mentions "new Python project", "uv init", or "Python scaffold". Do NOT use for Go, Rust, Node, or Terraform projects; use the matching scaffold-<lang> skill.

Scaffold a complete Rust project with CI/CD, release pipeline, and sr.yaml. Uses cargo as the native build system. Loads on top of scaffold-project (run that first for cross-language standard files). Use when creating a new Rust CLI, library, or workspace, or when the user mentions "new Rust project", "cargo init", or "Rust scaffold". Do NOT use for Go, Python, Node, or Terraform projects; use the matching scaffold-<lang> skill.

Scaffold a Terraform infrastructure project with CI/CD (plan on PR, apply on push), AWS OIDC auth, .envrc, and standard files. Uses terraform CLI as the native tool. Loads on top of scaffold-project (run that first for cross-language standard files). Use when creating infrastructure repos, or when the user mentions "new Terraform project", "terraform init", "AWS infra", or "infrastructure scaffold". Do NOT use for Go, Rust, Python, or Node application projects; use the matching scaffold-<lang> skill.

Defines GitHub Actions workflow structure: ci.yml + release.yml naming, concurrency groups, bot-commit skip, workflow_call reuse, App-token checkout, and optional fsrc/teasr steps. Language-specific pipelines live in scaffold-rust, scaffold-go, scaffold-python, scaffold-node, scaffold-terraform. Use when setting up GitHub Actions, wiring ci.yml/release.yml, configuring concurrency or workflow_call, or adding fsrc/teasr steps. Do NOT use for sr.yaml schema, typed publishers, or the sr CLI/action; use sync-release for those.

Per-language runtime version managers (fnm, uv, rustup) plus the vanilla-direnv .envrc pattern (layout python, use fnm, PATH_add, dotenv, source_up) for project dev environments. Use when bootstrapping a project's local toolchain, choosing a version manager, or writing a project .envrc. For chezmoi-managed pinned installer scripts and the tracked dot_envrc.project.example template, use setup-devenv-with-chezmoi.