dotagents

Helps author and review Architecture Decision Records that preserve one significant technical decision, its context, status, and consequences. Use when a bounded decision is made or needs a lightweight durable record, especially alongside source code.

Authors and audits A2A-compliant agent-card.json files: the machine-readable discovery metadata that lets other agents find, route to, and invoke an agent's skills. Covers all required and optional JSON fields, skill declaration quality (description, examples, tags), capability flags, security schemes, and alignment between the card and the agent's runtime SKILL.md. Use when creating a new agent, auditing an existing agent-card.json, or adding/modifying skills declared in a card.

Authors self-contained agent skills by extracting user workflows, interviewing for intent and edge cases, and designing modular packages with progressive disclosure (lean SKILL.md body, on-demand references/), writing step-by-step instructions with gotchas and validation loops, structuring directory trees (references/, assets/, scripts/), and enforcing the full spec checklist before deployment. Use whenever the user asks to create a new agent skill, extract expertise into a skill package, build a reusable workflow, audit an existing skill for compliance, or convert rough notes into a structured SKILL.md.

Authors, rewrites, and audits AGENTS.md instruction files using a discoverability-first rubric. Use when creating AGENTS.md, CLAUDE.md, or repository agent instructions; pruning stale or redundant guidance; adding nested instructions; or reviewing whether a rule earns permanent context.

Authors and audits code comments that explain intent, constraints, invariants, workarounds, security, performance, or public API contracts without narrating the code. Use when writing comments, TODOs, docstrings, godoc, Javadoc, JSDoc, or TSDoc; reviewing comment quality; or updating comments beside changed code.

How to write one atomic commit for a code change - Conventional Commits format, imperative subject, why-not-how body. Use whenever you commit code (git_commit): one node's work is exactly one reviewable, testable commit.

The disciplined way to build a new feature: understand the real problem, reuse or extend before you add, prefer a proven library over hand-rolled code, work the edge cases until the design holds, gate on functional tests, then implement to green. Load whenever the task is to add a feature, capability, command, endpoint, or non-trivial new behavior to a codebase - before you start designing or writing code.

The disciplined way to fix a bug: build a root-cause theory by reading the code, prove it with a test that fails for the right reason, then implement until that test goes green and the wider suite stays green. Load whenever the task is to fix a bug, defect, regression, crash, wrong output, or "it should do X but does Y" in existing code - before you start editing.

Reformats a Markdown document for clean visual rendering - consistent whitespace, heading hierarchy, scannability, and formatting consistency. Preserves all content and links exactly. Use before returning any Markdown document to the user, or when asked to clean up, format, or tidy Markdown output.

Authors and reviews executable issues, tickets, work items, bug reports, and feature requests across GitHub, Jira, Linear, Azure DevOps, and similar trackers. Use when work needs a clear outcome, bounded scope, sufficient context, and testable completion criteria before assignment.

Authors mermaid diagrams that actually render on the target platform. Covers all 31 diagram types in mermaid 11.16.0 — flowchart, sequence, class, state, ER, gantt, gitGraph, C4, architecture, mindmap, and the long tail — with per-diagram syntax, node shapes, and worked examples. Use when writing or fixing any ```mermaid block, choosing which diagram type fits, debugging a diagram that renders as a broken box on GitHub, or deciding whether a diagram type is supported by the renderer you are targeting.

How to write a pull request - a title and a description that tell the reviewer what changed, why, and how to verify it, scaled to the size of the change. Use when composing a PR for delivery.

How to research a git repository's code, structure, or conventions: clone it shallowly and read it locally with your filesystem tools instead of fetching github.com pages over the web. Load when a task involves understanding a codebase, a repo's layout, its conventions, how a feature is implemented, or anything answerable from the repository's own files.

Designs and reviews HTTP APIs and OpenAPI contracts: resource modeling, method and error semantics, schema composition, versioning, deprecation, compatibility, security, and validation. Use when creating or reviewing an OpenAPI document, planning an API version or sunset, assessing a compatibility change, or designing a REST-style endpoint.

The repeatable process for reviewing a code change: understand the change's intent before critiquing, read the diff AND the surrounding code, verify the change's claims and tests rather than trusting them, categorize each finding by severity, and structure the written review. Load whenever the task is to review a pull request, diff, branch, or proposed code change - before you start reading the diff.

Helps author and review Requests for Comments and equivalent prospective design proposals. Use when a substantial, cross-team, public-interface, or hard-to-reverse change needs explicit review and a defined decision before implementation.

Helps author and review exploratory Requests for Discussion and equivalent early-stage documents. Use when a problem, opportunity, or technical question needs shared framing before choosing a concrete solution or escalating to a formal proposal or decision record.