agent-skills

Use whenever creating CLAUDE.md, AGENTS.md, GEMINI.md, or other AI coding assistant instruction files at any scope level (user/global, project root, parent folder, subdirectory). Covers scope diagnosis, content taxonomy, multi-tool compatibility for Claude Code, Codex, Gemini CLI, and OpenCode, plus cookbook templates for Python, TypeScript, monorepo, agent/MCP, and minimal projects. Invoke when the user asks to "create a CLAUDE.md", "set up Claude for this project", "what should go in my AGENTS.md", "write agent instructions", "help me set up my global Claude configuration", or any similar request — even without explicit mention of CLAUDE.md or AGENTS.md. If the user is starting a new project or onboarding into an existing one and no instruction file exists, proactively suggest creating one.

Use when creating, adding, or maintaining a skill in this agent-skills repo — especially a "working-with-X" skill that wraps external/official docs by fetching them (llms.txt, sitemap, or a curated URL list), storing them in references/, and keeping them current with an auto-update script plus freshness metadata. Covers the naming taxonomy (working-with-X / developing-X / topic skills), SKILL.md frontmatter, the doc-fetching cookbook, the doc-frontmatter.cjs freshness helpers, the Makefile/CI auto-discovery, and the registration checklist. Invoke on "create a skill", "add a working-with-X skill", "wrap these docs in a skill", "write an auto-update script", "add freshness metadata", or "add a skill to this repo".

Use when running, operating, or troubleshooting the BeadBoard dashboard and its macOS launchd services — `com.beadboard.dashboard` (Next.js UI on :3000), `com.beadboard.daemon`, install.sh/uninstall.sh, the dashboard HTTP API, the Dolt↔JSONL sync architecture (`export.auto`, the `.beads/issues.jsonl` file-watcher), the `verify-sync.sh` diagnostic, env vars (`BEADS_DOLT_SHARED_SERVER`, `BEADS_DOLT_SERVER_PORT`, `BB_AGENT`), service file paths, and the operating/maintenance runbooks. Invoke on "dashboard won't start", "beadboard service", "launchctl beadboard", "is BeadBoard running", "verify-sync", "JSONL drift", "kickstart the dashboard", "EADDRINUSE on 3000". This is the ops/infra layer. For the agent-side coordination contract (the Iron Law, session lifecycle, mail categories, agent states, evidence flow) use `beadboard-driver`; for day-to-day `bd` conventions/troubleshooting use `beads-operations`; for the shared Dolt server internals use `working-with-dolt`.

Use when running, maintaining, or troubleshooting beads (`bd`) day-to-day — deciding bd vs TodoWrite, Joe's shared-server conventions (`bd init --shared-server --skip-agents`, the shared Dolt server on port 3308), the ready→claim→note→close workflow, compaction recovery, recovering from broken/nasty beads states (stale ports, orphan/duplicate Dolt servers, db-name mismatch, "database is locked"), and taming the `bd prime` session-start injection (the workflow preamble, `PRIME.md` customization, neutralizing the conservative git policy). Invoke on "beads is broken", "bd won't start", "set up beads in this project", "how do I track this", "bd prime is noisy", "change the session-start beads text", or any beads failure. For the raw CLI reference, use `working-with-beads`.

Use when designing, building, reviewing, testing, or improving agents, agentic workflows, agent skills, MCP servers, tool interfaces, subagent systems, or agent-development methodology