
Git best practices — conventional commits, staging, push policy, pre-commit gates, repo governance. USE WHEN committing, pushing, creating PRs, branch protection, rulesets, CODEOWNERS, pre-commit hooks, blocking known-dangerous strings.
Provenance tracking and sync for inherited rules, skills, and agents. USE WHEN drift, sync, publish prompts, inheritance, upstream, propagate, adapt rules, check provenance.
Find, read, create, validate, and capture Architecture Decision Records. USE WHEN ADR lookup, architecture decision, project context, decision history, create ADR, new ADR, validate ADR, capture ADRs, decisions directory, or editing any ADR file.
Bash and shell scripting pitfalls — BSD vs GNU tools, set -euo pipefail traps, glob behavior, subprocess env. USE WHEN writing or reviewing shell scripts (.sh files), Makefiles with shell recipes, or install scripts.
Collaborative ideation before implementation — explore context, clarify intent, propose approaches. USE WHEN starting creative work, new features, design decisions, or modifying behavior.
Build distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. USE WHEN the user asks for web components, pages, landing pages, dashboards, React / HTML / CSS layouts, or styling of any web UI. Not for backend or non-UI work.
Design, build, and validate forge modules. USE WHEN create module, new module, scaffold module, validate module, check module, audit module, module structure, module conventions, module architecture.
Create, validate, or audit agent definitions. USE WHEN create agent, new agent, build agent, scaffold agent, validate agent, audit agents, agent conventions, agent frontmatter.
Create, derive, and validate .mdschema files for markdown documents. USE WHEN create schema, add schema, derive schema, validate schema, check schema, mdschema, lint schema, heading rules, frontmatter validation, or editing any markdown file in a directory that contains a .mdschema.
RTK (Rust Token Killer) — token-optimized CLI proxy for Claude Code. USE WHEN rtk, token savings, optimize tokens, reduce tokens, command optimization.
Create a detailed implementation plan with bite-sized tasks. USE WHEN spec approved, plan implementation, create plan, write implementation plan.
Check the forge ecosystem for staleness — installed skills vs source, binary freshness, lib consistency, version drift, submodule pointers, hook config. USE WHEN stale, freshness, out of date, check staleness, need to rebuild, make install needed, system check.
Validate and minimize prompts — provenance, targeting, staleness, redundancy, ablation testing, perplexity scoring. USE WHEN audit rules, check provenance, minimize prompts, prompt cleanup, validate targeting, find redundant rules, prompt audit, prompt analysis, stale rules.
Create, validate, and publish Claude Code plugins from forge modules. USE WHEN create plugin, validate plugin, publish plugin, marketplace, plugin.json, cowork plugin.
Ship artifacts (rules, skills, agents) from forge into downstream repos with provenance tracking and sync. USE WHEN drift, sync, publish artifact, publish prompts, publish skills, publish agents, inheritance, upstream, propagate, check provenance.
Capture, list, update, and close repo-local backlog items as Obsidian Tasks lines in dated daily files under docs/todos/. USE WHEN capture todo, project todo, project backlog, repo backlog, backlog item, list todos, todo capture, new todo, close todo, or local issue tracking without GitHub.
Apply targeted transforms to prompt-shaped documents: align conventions, debrand vendor references, minimize filler, rescope tool grants, extract bulk reference, adapt for downstream repos. USE WHEN refining an adopted skill, polishing an authored skill/rule/agent, removing rot, or porting prompts across repos.
Adopt a community skill from an upstream URL into forge. Fetches the source, applies transforms, produces a working SKILL.md with SLSA provenance. USE WHEN adopting a community skill from aitmpl, anthropics/skills, or a similar catalog.
Build distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. USE WHEN the user asks for web components, pages, landing pages, dashboards, React / HTML / CSS layouts, or styling of any web UI. Not for backend or non-UI work.
Safety guardrails: runtime overrides for AI-safety plugin blocks, and per-language security review for python, javascript/typescript, and go. USE WHEN a safety plugin blocks a command, sandbox blocked, git reset --hard blocked, rm -rf blocked, workaround for a blocked command, safety plugin configuration, security review, secure-by-default coding, vulnerability report.
Markdown authoring and linting conventions for forge — fence tags, table alignment, link paths, reference-style labels, README language switchers, and the Linting workflow. USE WHEN editing any markdown file, or invoking lint.
Review your own staged changes via a code-review TUI before triggering a commit. USE WHEN about to commit, walking through your own staged diff, self-reviewing before approval, tuicr, revdiff, git diff cached.
Author project documentation that future humans (and AI sessions) actually read. Covers TLDRs for tools, READMEs, runbooks, journals. USE WHEN write documentation, create tldr, tool one-pager, document a cli, write readme, runbook, journal entry, capture knowledge about a tool, distill a session into reusable notes.
Decompose a research question into sub-queries, spawn parallel WebResearcher agents per angle, synthesize findings with citations and explicit confidence. USE WHEN the user asks to research, investigate, look online, look up, dig into, find sources, gather evidence, or survey what's known about a topic. Single-pass; for multi-round adversarial research use ResearchCouncil in forge-council.
Commit-time secret scanning with gitleaks — prevent credentials from entering git history. USE WHEN scanning for leaked secrets, setting up pre-commit hooks, or auditing repositories for credentials.
Remove hardcoded vendor names, brand references, and external-service dependencies from a prompt-shaped document. USE WHEN an adopted skill hardcodes specific tool names, company brands, or paid service dependencies that would bias the skill toward one ecosystem.
Create and validate skills for forge modules. USE WHEN create skill, new skill, write skill, validate skill, check skill, skill structure, skill conventions.
Execute an implementation plan inline — task by task in a single session. USE WHEN executing plan, run plan, implement plan, inline execution.
Move bulk reference material from the main SKILL.md body into @-included companion files so the always-loaded content stays lean. USE WHEN an adopted or authored skill's body exceeds its information density because it inlines reference tables, pricing, catalogs, or per-variant guidance.
Adopt a community skill from an upstream URL into forge. Fetches the source, applies transforms, produces a working SKILL.md with SLSA provenance. USE WHEN adopting a community skill from aitmpl, anthropics/skills, or a similar catalog.
Cite origins for every factual data point (number, date, limit, rate, threshold) via markdown reference-style links. USE WHEN writing docs, ADRs, READMEs, or any file that asserts factual claims.
Remove motivational, marketing, and filler prose from a prompt-shaped document while preserving directive content. USE WHEN adopting a community skill, authoring a skill or rule that feels bloated, or auditing an existing artifact for token waste. Applies MVPR principles.
Check for relevant skills before responding to a user message, including before clarifying questions. USE WHEN you are about to reply and have not verified whether a skill applies. Applies universally.
Language and framework specific security reviews for python, javascript/typescript, and go. USE WHEN the user requests a security review, secure-by-default coding help, or a vulnerability report. Not for general code review or debugging.
Reactive correction and root-cause fix. USE WHEN something went wrong, user is frustrated, demands a correction, says wtf, what the hell, why did you, that's wrong, this is broken, no not that, stop. Executes the immediate fix, then hunts the upstream artifact that caused it and creates a corrective change.
Audit and clean AI coding tool settings — permissions, plugins, hooks, cross-layer conflicts. USE WHEN review permissions, clean settings, audit config, plugin conflicts, hook audit, settings cruft.
Tighten a prompt-shaped document's tool scope to the narrowest set it actually uses. USE WHEN an adopted or authored skill declares allowed-tools: '*', omits the frontmatter field entirely, or grants tools the workflow never invokes.
Generate single-file HTML demos comparing techniques side-by-side. USE WHEN preview css, compare css, css demo, show options, visual comparison, html playground, render demo.
Extract session learnings and apply them as updates to rules, skills, and agents. USE WHEN session produced reusable patterns, corrections, or conventions worth capturing.
Audit forge module provenance and deployment integrity — inspect deployed sidecars, detect drift, clean stale artifacts after renames, trace adoption chains. USE WHEN running forge provenance, auditing a deployed target, debugging drift, cleaning up after a skill rename, or investigating sidecar state.
Create and validate module hooks. USE WHEN create hook, new hook, write hook, scaffold hook, validate hook, check hook, hook conventions, hook events, hook structure.
Write a formal design spec from brainstorming output or requirements. USE WHEN design approved, write spec, formalize design, spec document.
Verify work before claiming done. USE WHEN about to claim work is complete, fixed, or passing, before committing or creating PRs.
Adapt generic rules and prompts for independent repos — strip forge branding, add path scoping, drop irrelevant rules, preserve custom overrides. USE WHEN adapt rules, adapt prompts, port rules, specialize rules, sync rules, update rules for repo, downstream repo, consumer repo.
Format and lint a markdown document — backtick code references, fix bare URLs, check list formatting and heading hierarchy. USE WHEN a document needs formatting cleanup, code references are not backticked, markdown quality needs improvement, or lint markdown.
Fix indentation, fence language tags, heading depth, and frontmatter fields to match forge conventions. USE WHEN an adopted community skill or any prompt-shaped document fails a forge convention check (indent, fence, heading, schema).
--- mode: append --- @GeminiAgent.md
Scan a dotfiles tree for secrets via gitleaks, aggregate findings by top-level directory and rule, then surgically filter flagged lines from shell-history files before importing into atuin. USE WHEN auditing dotfiles before pushing to a public repo, scanning rsynced dotfiles-private contents, importing legacy zsh or bash history into atuin, filtering credential leaks out of a shell history file, deciding which dotfile subdirectories can be made public.
Defensive programming principles for robust systems — input validation, error boundaries, fail-safe defaults, invariant checking. USE WHEN writing production code, designing APIs, handling external input, or reviewing error handling.
Decide how to integrate completed work — merge, PR, or cleanup — once implementation is done and tests pass. USE WHEN implementation is complete and tests pass, deciding merge strategy, or cleaning up a feature branch.
Run tests and systematically fix all failing tests using smart error grouping. USE WHEN tests are failing, user asks to fix failing tests, CI reports test failures, or a test suite run leaves failures.
Fix issues end-to-end — triage, diagnose, branch, fix, PR/MR, close. Supports GitHub (gh) and GitLab (glab) with cross-repo fixes and submodule bumps. USE WHEN fix issue, github issue, gitlab issue, bug report, fix bug, resolve issue, triage issue, gh issue, fix
Architecture for security and health-check programs: standalone-runnable checks, severity ladder with UNKNOWN, key:value output contract, orchestrator dispatch, exit-code semantics. Language-agnostic; reference implementations in Bash, applies to Python and other languages. USE WHEN writing health checks or audit tools, designing check-script contracts, adding checks to tools like check-mac, reviewing health-check architecture, or porting a check tool between languages.
Architecture for security and health audit scripts: standalone-runnable checks, severity ladder with UNKNOWN, key:value output contract, orchestrator dispatch, exit-code semantics. Language-agnostic; reference implementations in Bash, applies to Python and other languages. USE WHEN writing audit tools, designing check-script contracts, adding checks to tools like check-mac, reviewing audit-script architecture, or porting an audit tool between languages.
Inspect failing GitHub Actions checks via gh, pull logs, summarize root cause, and propose a fix plan. USE WHEN a GitHub PR has failing CI checks, debugging GitHub Actions failures, or triaging CI breakage before merging.
Author a clear scoped request when asking for a code review. USE WHEN ready for review, finishing a task, opening a PR, or requesting review feedback on a piece of code.
Delegate independent tasks from an implementation plan to subagents. USE WHEN a plan has independent tasks suitable for parallel subagent execution, multi-agent implementation, or delegating parts of a plan.
Four-phase debugging methodology — root cause before fixes. USE WHEN encountering any bug, test failure, unexpected behavior, or build failure.
Test-driven development practices — Red-Green-Refactor cycle, test categories, coverage strategy, property-based testing. USE WHEN writing tests, designing testable APIs, or reviewing test coverage.
Process code review feedback with technical rigor — verify before implementing, push back when wrong. USE WHEN receiving code review feedback, before implementing review suggestions.
Proactive code cleanup — duplication removal, pattern adoption, defensive hardening, readability maximization. USE WHEN cleanup, refactor, code quality, reduce duplication, adopt patterns, readability, make code explicit, clean up code, polish code.
GitHub CLI reference — repo management, releases, Actions/CI, PR operations, branch protection, labels. USE WHEN github, gh, repo, release, actions, ci, workflow, branch protection, labels, milestones.
Server-rendered web dashboards and apps in Rust using axum + htmx + Askama + rust-embed. USE WHEN building a web dashboard, adding a web UI to a CLI tool, server-rendered HTML, htmx partials, Askama templates, axum routes, embedded static assets, localhost webserver.
Rust development conventions — crate structure, error handling, CLI patterns, config loading, testing, and cross-platform compilation. USE WHEN writing Rust code, creating binaries, designing library APIs, or reviewing Rust implementations.
Build static HTML data explorer apps from SQL databases or datasets. Vega-Lite or Chart.js for charts, Tabulator for tables, vendored JS. Produces standalone HTML files suitable for SharePoint, Cloudflare Pages, or email.
Choose and configure visualization tools for data explorer apps. Vega-Lite for declarative charts, Chart.js for Sankey and custom visualizations, Tabulator for interactive tables.
Bash and POSIX shell conventions for the forge ecosystem — idioms over subprocesses, fail-safe defaults, probe guarding, multi-line command substitution, exit-code semantics. USE WHEN writing or reviewing shell scripts (audit tools, hooks, build scripts), designing CLI flag handling, or wiring shell tools into CI.