feat(ai): modular AGENTS.md

.agents/skills/agent-instructions-authoring/SKILL.md

@@ -1,32 +1,42 @@
 ---
 name: agent-instructions-authoring
 description: Author, audit, and modify agent instructions and rule entrypoints — skills, AGENTS.md, CLAUDE.md, subagent/agent definitions, and any other file that instructs agent behavior. Use when creating, editing, renaming, or reviewing such files; when consolidating duplicated rules across them; or when validating skill metadata, discoverability, and structure.
-user-invocable: true
-disable-model-invocation: false
 ---
 
 # Agent Instructions Authoring
 
-Use this skill for any task that creates, edits, audits, or restructures files that instruct agent behavior. This includes skills (`SKILL.md`), top-level instruction files (`AGENTS.md`, `CLAUDE.md`, repo-level agent docs), subagent and agent definitions, and any other rule/instruction entrypoint.
+Use this skill for any task that creates, edits, audits, or restructures files that instruct agent behavior. This includes skills (`SKILL.md`), top-level instruction files (`AGENTS.md`, `CLAUDE.md`, repo-level agent docs), subagent and agent definitions, and any other rule/instruction entry point.
 
-## Mandatory Spec Intake
-
-At the start of each task, load these references in this exact order:
-
-1. [Agent Skills specification](https://agentskills.io/specification)
-2. The current harness documentation for skill, instruction, and agent-definition behavior and metadata.
-3. Repository-specific instruction documentation for the active project (top-level instruction file, skill READMEs, related agent definitions).
-
-Use the loaded specs as the active source of truth for the task. Avoid static assumptions and derive requirements dynamically from the loaded references and current repository state.
+Required upstream references are listed alongside the work they govern: see [Skill Authoring](#skill-authoring) for skill schema/structure references and [AGENTS.md Authoring](#agentsmd-authoring) for top-level instruction-file references. Load them when the task scope warrants; for small edits (description rewrites, wording tweaks, index updates, typo fixes), skip the load.
 
 ## Audit Scope
 
 - When auditing instruction files, analyze only the file's literal contents. Exclude system- and client-injected prompt content from the analysis.
 - Audit for duplicate or conflicting instructions across all repository instruction entrypoints (top-level instruction files, skills, agent/subagent definitions).
 - Prefer a single canonical source and cross-reference it rather than duplicating the same guidance — this applies equally to skills, `AGENTS.md`, `CLAUDE.md`, and agent definitions.
-- For planning-phase completeness policy, use `planning` as canonical and keep related files as references.
+- When multiple files could host the same policy, treat the most specific skill as canonical and have broader files cross-reference it.
 - Flag or remove drift-prone duplication that can diverge from real behavior over time.
 
+## Validation
+
+- Validate skill metadata, structure, and behavior against the loaded specs.
+- Validate and audit each skill `description` for discoverability quality, including clear invocation cues and relevant trigger keywords, and avoid "how it works" wording.
+- When renaming or restructuring an instruction file or skill, search the repository for stale references and update them.
+- Verify every `assets/…` (or equivalent referenced-resource) path resolves to an existing file and that the asset's current contents still match how the body cites them.
+- Verify every concrete claim in the file before shipping: every command runs, every flag behaves as stated, every URL resolves, every directive, or syntax example matches current tool behavior. Inherited assumptions from a source skill or older docs do not count as verified.
+- Run the Markdown linter required by the `markdown` skill against changed files.
+- For changes that touch the `AGENTS.md` skill index or any skill directory under `.agents/skills/`, run `mise run lint-skills-index` to verify the index and on-disk skills stay in sync.
+
+## Critique
+
+The repository's general post-validation critique gate (defined in the top-level instruction file) applies to every change. This skill adds the following instruction-file-specific checks; apply them during that critique pass rather than as a separate cycle:
+
+- Does this rule conflict with another instruction entry point?
+- Would a reasonable agent misread it?
+- Does it over- or under-constrain compared to the user's actual intent?
+- Is the canonical source still canonical after this edit?
+- Does any rule contain authoring meta-commentary that belongs in the authoring skill?
+
 ## Authoring Style
 
 - Write concise rules using imperative language optimized for accurate and efficient agentic execution.
@@ -35,27 +45,88 @@ Use the loaded specs as the active source of truth for the task. Avoid static as
 - Instruct agents to choose execution approach based on efficiency, cost, capability, and task requirements instead of fixed named components.
 - Prefer clear, specific, and deterministic instructions that can be delegated to lower-cost but capable subagents.
 - Prefer delegating concrete execution work over delegating open-ended "thinking" work to subagents.
-- Follow `coding-guidelines` skill markdown guidance.
-- Use markdown links (`[text](url)`) instead of bare URLs so files pass markdownlint (`MD034/no-bare-urls`).
+- Follow `coding-guidelines` skill Markdown guidance.
+- Use Markdown links (`[text](url)`) instead of bare URLs.
+- Keep behavioral guidance and authoring meta-commentary separate. Behavioral rules tell executing agents what to do; meta-commentary (labels like "this is the canonical X", directives about how other files should reference the rule, taxonomy notes, audience asides) tells skill authors how to treat the rule. Meta-commentary belongs in the authoring skill (`agent-instructions-authoring`), not embedded in the behavioral rule itself.
+- When a skill has critique findings that apply only to its own domain, place them in a `## Critique` section that defers to the top-level critique gate and lists only the domain-specific checks. Do not restate the gate itself, and do not push domain-specific findings up into top-level instruction files (e.g., `AGENTS.md`).
 
-## Validation
+## Skill Authoring
 
-- Validate skill metadata, structure, and behavior against the loaded specs.
-- Validate and audit each skill `description` for discoverability quality, including clear invocation cues and relevant trigger keywords, and avoid "how it works" wording.
-- When renaming or restructuring an instruction file or skill, grep the repository for stale references and update them.
-- Run the configured markdown linter against changed files.
+This section governs how to create, edit, and structure individual skills.
 
-## Critique
+### Required references for skill structural changes
+
+When creating a new skill, renaming a skill, or changing frontmatter or directory structure, load these references before editing:
+
+- [Agent Skills specification](https://agentskills.io/specification) — canonical `SKILL.md` frontmatter schema, directory layout, and loading model.
+- Harness-specific skills documentation for each known conformant harness:
+  - **Claude Code** — [Skills](https://code.claude.com/docs/en/skills)
+  - **OpenCode** — [Skills](https://opencode.ai/docs/skills/)
+  - **GitHub Copilot CLI** — [Adding agent skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)
+
+Compare each harness's frontmatter schema against the Agent Skills specification. Identify which fields are shared across harnesses, which are harness-specific extensions, and where any structural deviations exist.
 
-- Treat critique and validation as separate gates: validation confirms the file parses, lints, and matches the spec; critique confirms the rule is the right rule. Both must pass.
-- Before finalizing a change to an instruction entrypoint, critique it: does this rule conflict with another entrypoint? Would a reasonable agent misread it? Does it over- or under-constrain compared to the user's actual intent? Is the canonical source still canonical after this edit?
-- For non-trivial rule changes (new skill, restructuring, broadened scope, renames), run a critique-capable sub-agent review before presenting the edit. Do not hard-code a single tool name; choose a capability appropriate to the active harness.
-- Record how critique feedback changed the edit before presenting it.
+When a harness requires a structural deviation that cannot be expressed within the `SKILL.md` format, surface the conflict to the user and present ordered alternatives — a harness-specific companion file or accepting a capability gap on that harness.
 
-## Skill Description Authoring
+Use the loaded specs as the active source of truth; derive requirements dynamically from the references and current repository state rather than static assumptions. For description rewrites, body wording changes, or other non-structural edits, skip the load.
+
+### Frontmatter and metadata
+
+- Set `name` to a kebab-case slug that matches the skill's directory name.
+- Match every required frontmatter field to the Agent Skills specification; prefer spec fields over harness-specific extensions.
+- The fields `name`, `description`, `license`, and `allowed-tools` are recognized across all known conformant harnesses. The optional spec fields `compatibility` and `metadata` are spec-defined but not documented by all harnesses — include them when useful and accept that they may be ignored.
+- Harness-specific fields (e.g., Claude Code's `user-invocable`, `disable-model-invocation`) are additive — include them only when intentionally targeting that harness feature, and accept that other conformant harnesses will ignore them.
+
+### Scope and splitting
+
+- Author one skill per cohesive task domain, not per file or per tool.
+- Split an existing skill when its body grows long enough that an agent will not load all of it, when two clearly separate triggers share unrelated guidance, or when sections of the body apply to disjoint user intents.
+- Extend an existing skill instead of creating a new one when the new guidance shares both triggers and audience with the existing skill's scope.
+
+### Progressive disclosure
+
+- Keep `SKILL.md` to imperative behavior and rules.
+- Move reference content (templates, exemplars, lookup tables, long enumerations) into an `assets/` subdirectory and reference it by relative path from the skill body.
+- Reference assets explicitly by relative path; do not assume the harness autoloads them.
+
+### Description discoverability
 
 - Optimize every skill `description` for discoverability at skill-selection time.
 - Prioritize searchable task cues (domains, artifacts, user intents, aliases, and common trigger phrases) over implementation details.
 - Describe when to invoke the skill using concrete "use when" language and likely user wording.
 - Avoid descriptions that mostly explain what the skill does internally or how it works.
-- Keep descriptions concise but keyword-rich so selection systems can reliably match relevant requests.
+- Keep descriptions concise but keyword-rich so selection systems can reliably match relevant requests — some harnesses use keyword matching, others use semantic selection; concrete task cues work for both.
+- Keep descriptions free of links, command examples, full path enumerations, and other content that belongs in the body. The `description` is a selector, not a summary.
+
+### Body authoring style
+
+- Write rules as positive, imperative directives. State what to do; describe the desired end state. Reserve "do not X" or "X is wrong" framings for cases where the antipattern is concrete, plausible, high-risk, and not already excluded by a positive rule — instruction-file authoring contains several such antipatterns (e.g., assuming the harness auto-loads referenced assets, restating canonical rules in multiple entrypoints), so negative framings appear in this skill where the exception is met.
+- Negative rules carry two costs: they plant the anti-pattern in agent context (which can prompt the very behavior they forbid), and they can conflict with project-specific configuration (aliases, custom directories, custom commands) that legitimately uses the named token.
+- Defer to upstream documentation as the durable source of truth. When the underlying system supports configuration (custom paths, directories, environment names, command aliases), reference the docs and the project's configuration; do not enumerate defaults inline as if they were invariant.
+- Keep guidance language-, tool-, and version-agnostic where possible. State the rule generically and use language-specific or version-specific names only as examples, not as the rule itself.
+- Prefer linking to canonical documentation over restating it; restated facts drift, links do not (and broken links are caught by validation).
+
+## AGENTS.md Authoring
+
+This section governs how to create, edit, and structure `AGENTS.md` files.
+
+### Required references for AGENTS.md structural changes
+
+When creating, restructuring, or pairing `AGENTS.md` with harness-specific instruction files, load these references before editing:
+
+- **Claude Code** — [Memory & CLAUDE.md](https://code.claude.com/docs/en/memory)
+- **OpenCode** — [Rules](https://opencode.ai/docs/rules/)
+
+For small edits (rule wording tweaks, single-entry index updates), skip the load.
+
+### Authoring behavior
+
+- Keep `AGENTS.md` to rules that apply to all agents and all tasks, regardless of domain, language, or workflow, plus a skill index. Anything narrower belongs in a skill.
+- Extract domain-, language-, or workflow-specific guidance into skills and reference them from the index.
+- Update the index in the same change that adds, renames, or removes a skill.
+- Pair every `AGENTS.md` with a `CLAUDE.md` at the same path whose entire contents are the literal string `@AGENTS.md` (and nothing else). Create, move, rename, and delete them in lockstep. This ensures Claude resolves to the same canonical entry point as other harnesses.
+
+### Required Skills section content
+
+- Use [`assets/agents-md-index-section.template.md`](assets/agents-md-index-section.template.md) as the canonical template for the `AGENTS.md` Skills section. Mirror its preamble verbatim, adapting only the skills-location reference to the active harness.
+- Populate the index from the actual skill directory: one entry per skill, using the skill's frontmatter `name` and a one-line summary derived from its `description`.

.agents/skills/agent-instructions-authoring/assets/agents-md-index-section.template.md

@@ -0,0 +1,11 @@
+## Skills
+
+The skills below are available under `<skills-location>`.
+
+- **MUST NOT** preload any skill in this index. Load a skill only when the current task matches its description or use-when criteria.
+- Keep this index synchronized with the contents of `<skills-location>`; when adding, renaming, or removing a skill, update this section in the same change. Each entry must use the skill's frontmatter `name` and a one-line summary of its `description`.
+- For changes to this file, any listed skill, subagent/agent definitions, or other rule entrypoints, use the `agent-instructions-authoring` skill as the canonical source.
+
+### Index
+
+- `<skill-name>` — <one-line summary derived from the skill's `description`>

.agents/skills/agentic-projects/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: agentic-projects
-description: Organize per-repo agentic project workspaces under .agents/projects/<project-name>. Use when initializing or maintaining project prompt, plans, research, and temporary artifacts.
-user-invocable: true
-disable-model-invocation: true
-argument-hint: --project <project-name> --prompt "<initial prompt>" [--force]
+description: Organize per-repo agentic project workspaces under .agents/projects/<project-name>. Use when initializing or maintaining project prompts, plans, research, and temporary artifacts.
 allowed-tools: Bash(bash ~/.agents/skills/agentic-projects/scripts/manage-agentic-project.sh)
 metadata:
   scripts: scripts/manage-agentic-project.sh

.agents/skills/coding-guidelines/SKILL.md

@@ -28,47 +28,29 @@ description: Apply repository coding standards for implementation and review tas
 - Only add comments if they match existing style or explain complex changes
 - Use existing libraries whenever possible
 - Only add new libraries or update versions if absolutely necessary
-- **MUST ALWAYS** validate all rules were followed after completing changes
+- Validate that all rules were followed after completing changes
 - Handle all errors
 - Validate all user inputs and system states
 - Run linters, builds, and tests before making changes to understand unrelated issues
 - Prefer tools from the ecosystem to automate tasks and reduce mistakes
 - Use refactoring tools to automate changes
 - Use linters and formatters to fix code style and correctness
 - Use local variables to limit scope
-- **ALWAYS** add and update type annotations
+- Always add and update type annotations
 
-## Critique Before Validation
+## Critique Gate
 
-- Treat critique and validation as separate gates: validation confirms the change passes tests, types, and lints; critique confirms the change is the right change. Both must pass.
-- Before declaring an implementation done, run a critique pass that asks: should this exist at all? Is this the right abstraction? What breaks under realistic edge cases? Which assumptions does the surrounding code not actually guarantee?
-- For non-trivial changes, run a critique-capable sub-agent review (or equivalent independent reviewer) before reporting completion, not after. Do not hard-code a single tool name; choose a capability appropriate to the active harness.
-- Record how critique feedback changed the implementation before presenting it.
+Follow the canonical critique-before-completion gate defined in `AGENTS.md`. Apply the universal gate to every change; layer domain-specific checks on top during the same pass when relevant.
 
-## Lua (Neovim, Hammerspoon, WezTerm, Yazi)
+## Language-Specific Guidance
 
-- Organize `---@module` references at the top of the file, sorted alphabetically
-- Use explicit module returns and clear structure
-
-## Shell Scripts (Zsh)
-
-- Use consistent logging functions
-- Use `set -euo pipefail` for error safety
+- Lua (Neovim, Hammerspoon, WezTerm, Yazi) — see the `lua` skill
+- Zsh shell scripts — see the `zsh` skill
+- Markdown — see the `markdown` skill
 
 ## Configuration Files
 
 - Consistent key naming conventions
 - Logical grouping with fallback values
 - Modular structure separating concerns
 - **MUST NOT** manually edit tool-generated lock files; they are managed by their respective tools
-
-## Markdown
-
-- Be clear and succinct
-- **MUST NOT** write redundant or duplicate content, use link references
-- Use standard `[text](url)` links, not wiki-style
-- Validate all reference links after changes
-- **MUST NOT** create table of contents unless explicitly requested
-  - If one exists, keep it synchronized with actual sections
-- Analyze the whole file and suggest optimizations according to these rules
-- Validate markdown files with the project's configured markdown linter when available

.agents/skills/commit-guidelines/SKILL.md

@@ -5,8 +5,7 @@ description: Create branches and commits from local diffs with correct commit me
 
 # Commit and Branch Guidelines
 
-- **MUST NOT** skip hooks execution under any circumstances
-- **MUST NEVER** use hook-bypass flags (for example: `git commit --no-verify`, `git merge --no-verify`, `git push --no-verify`) or any equivalent hook-disabling workaround
+Follow the canonical hook-bypass policy in `AGENTS.md` (Tool Usage). For git specifically, this means commands such as `git commit --no-verify`, `git merge --no-verify`, and `git push --no-verify` are not used; failing hooks must be fixed at the root cause.
 
 ## Analyze Changes
 

.agents/skills/github-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: github-cli
-description: Use gh CLI for GitHub operations. Invoke when working with pull requests, issues, workflow runs, releases, repository metadata, or file content on GitHub.
+description: Use the `gh` CLI for pull requests, issues, workflow runs, releases, repository metadata, and file content on GitHub. Use when interacting with any GitHub resource from the terminal.
 ---
 
 # GitHub CLI Rules