ai-agent-maintenance

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 atframe_utils. 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/<name>/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 <BUILD_DIR> 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 <BUILD_DIR>/_agent_tmp/....
• Keep this repository self-contained; do not mirror rules into parent, sibling, or vendored-submodule prompts.

References

• Read compatibility sources only when changing Skill formats, discovery paths, bridge behavior, client-specific configuration, MCP guidance, or cross-tool compatibility claims.
• Read upstream change-workflow methods only when changing risk routing or OpenSpec/Superpowers integration policy.