--- name: ai-agent-maintenance description: "Use when: initializing, auditing, or optimizing repository AI guidance, including AGENTS.md/CLAUDE.md bridges, Agent Skills, trigger descriptions, progressive disclosure, source tracking, or cross-tool compatibility. Do not use when: only implementing code under existing guidance." --- # AI Agent Maintenance Use this Skill for AI-facing surfaces in `libatbus`. Keep this repository self-contained; do not depend on parent, sibling, or vendored-submodule prompt files. ## Outcome - Keep AI-facing guidance source-backed, compact, task-routed, and independently usable in this repository. - Merge improvements into the current authoritative files; remove stale, duplicated, or historical variants. - Preserve the user's dirty workspace and avoid tool-specific configuration without a verified need. ## Workflow ### 1. Discover before loading - Inspect the active harness's actual Skills, tools, modes, permissions, and extensions. Do not assume another client's capabilities or install a workflow without user authorization. - Read `AGENTS.md`, `CLAUDE.md`, `.agents/skills/README.md`, repository status, and Skill `name`/`description` metadata first. Inspect whether tool-specific directories or AI docs exist; do not preload every Skill body or reference. - Load a full `SKILL.md`, bundled resource, legacy prompt, or client-specific config only when the task or index routes there. Read generated/template inputs when they are the real source of truth. ### 2. Verify facts and choose process strength - Separate stable repository facts from mutable external behavior. Verify the former in current code/config/tests and the latter in current official documentation before writing compatibility or security claims. - Treat OpenSpec and Superpowers as optional, mutable integrations. Verify repository adoption and the active harness's current capabilities before referencing their artifacts or commands; never install or initialize them implicitly. - State assumptions, the smallest sufficient plan, rollback, and validation after the source pass. - Use the shortest verified path for small, low-risk edits. Require reviewable scope and acceptance criteria before cross-module behavior, public API, data model, security, or deployment changes; reuse existing project artifacts rather than initializing a methodology for ceremony. ### 3. Choose one authoritative surface - Put stable, high-signal, broadly applicable rules in `AGENTS.md`. - Keep `CLAUDE.md` as a thin `@AGENTS.md` and Skill-index bridge; add only verified Claude-specific differences. - Keep `.agents/skills/README.md` to names, one-line routing, and compact maintenance rules. - Put repeatable, specialized procedures and non-obvious project knowledge in `.agents/skills//SKILL.md`. - Add client-specific rules, agents, prompts, or Skill mirrors only when the shared surfaces cannot express a verified requirement. Write only the difference and do not duplicate shared rules. ### 4. Maintain Skills for low context cost - Keep folder and `name` identical, lowercase, hyphenated, and at most 64 characters. Keep portable frontmatter to `name` and `description` unless a verified client-specific requirement justifies a separate client-owned surface. - Make `description` intent-first and specific: say what the Skill does, when it should trigger, and a useful near-miss boundary. Keep the key trigger early and stay within 1024 characters. - Write imperative, project-specific procedures. Remove explanations the agent already knows; use one clear default and make control stricter only where the workflow is fragile. - Keep the main body under 500 lines and about 5,000 tokens. Move detailed APIs, examples, and variants to one-level `references/`; keep deterministic repeated logic in tested, non-interactive `scripts/` with actionable errors. - For a new or materially changed trigger, draft 8-10 realistic should-trigger queries and 8-10 near-miss should-not-trigger queries. Measure invocation only when the active client exposes observable Skill calls; otherwise perform a manual boundary review and report that no trigger rate was measured. ### 5. Validate and report - Run an available Agent Skills validator; otherwise check YAML delimiters, required fields, folder/name equality, description length, referenced paths, and absence of placeholders directly. - Run markdown diagnostics, line-ending/trailing-whitespace checks, and scoped `git diff --check`. Re-read routing files to confirm bridges remain thin and references load only on demand. - Validate from every affected nested Git root. Run code/build/tests only when behavior or executable content changed; for documentation-only work, state what was skipped and why. - Report changed surfaces, verified sources, capability boundaries, validation results, and unresolved risks. ## Repository invariants - Keep engineering conventions in `../engineering-guidelines/SKILL.md`; route to them instead of duplicating details. - Resolve `` from the nearest VS Code CMake setting, clangd compile-command path, or existing configured tree; fall back to `build`. Put scratch and script/log output under `/_agent_tmp/...`. - Keep this repository self-contained; do not mirror rules into parent, sibling, or vendored-submodule prompts. ## References - Read [compatibility sources](references/compatibility-sources.md) only when changing Skill formats, discovery paths, bridge behavior, client-specific configuration, MCP guidance, or cross-tool compatibility claims. - Read [upstream change-workflow methods](../change-workflow/references/upstream-methods.md) only when changing risk routing or OpenSpec/Superpowers integration policy.