ai-agents-generation-and-release
Operate the ai-agents generation and release machinery, covering the seven build_all.py generators, generate_agents.py, the drift gates, the version-free plugin manifests, and the npm publish path. Use when you say `regenerate the mirrors`, `run the drift checks`, `why is the plugin version gate red`, `release the npm cli`. Do NOT use for environment setup (use `ai-agents-build-and-env`) or architecture rationale (use `ai-agents-architecture-contract`).
rjmurillo · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add rjmurillo/ai-agents --skill ai-agents-generation-and-release技能说明
name: ai-agents-generation-and-release
description: Operate the ai-agents generation and release machinery, covering the seven build_all.py generators, generate_agents.py, the drift gates, the version-free plugin manifests, and the npm publish path. Use when you say regenerate the mirrors, run the drift checks, why is the plugin version gate red, release the npm cli. Do NOT use for environment setup (use ai-agents-build-and-env) or architecture rationale (use ai-agents-architecture-contract).
version: 1.0.0
license: MIT
metadata:
routing:
role: conditional-adjunct
invoker: ai-agents-build-and-env
trigger: build-and-env redirects release work here
user-facing: false
ai-agents Generation and Release
Runbook for the build, generation, mirroring, versioning, and release machinery. Every command below was run or read from source on 2026-07-02/03 and re-verified on 2026-07-29; re-verify with the one-liners in Provenance before trusting a volatile number.
Jargon, defined once:
- Generator: a Python function or script that reads a canonical tree and writes a derived (generated) tree.
- Drift: the generated tree no longer matches what the generators would produce from the canonical tree.
- Canonical: the tree you are allowed to edit. Generated trees are outputs; you never hand-edit them.
- Semver: semantic version string MAJOR.MINOR.PATCH. The plugin manifests carry no version at all (ADR-092); the npm package still does.
Triggers
regenerate the mirrorsrun the drift checkswhy is the plugin version gate redrelease the npm cliwhy is the drift gate red
When NOT to Use This Skill
| You want | Use instead |
|---|---|
| Set up the dev environment, uv, hooks | ai-agents-build-and-env |
| WHY the seam is shaped this way, invariants | ai-agents-architecture-contract |
| Triage a red CI gate you do not understand | ai-agents-debugging-playbook |
| Change classification, commit caps, review gates | ai-agents-change-control |
| Escape hatches like the drift allowlist | ai-agents-config-catalog |
Process
Phase 1: Know the Seam Before You Edit
The generation seam is ASYMMETRIC (ADR-072 is PROPOSED and refines this; the running system is what follows). Find your file in this table BEFORE editing. Editing a generated tree is the classic failure (see Anti-Patterns).
| Tree | Role | Canonical source | Regenerated by |
|---|---|---|---|
templates/agents/*.shared.md | CANONICAL for agents | itself | n/a |
src/vs-code-agents/ | generated | templates/agents | build/generate_agents.py |
src/copilot-cli/agents/ | generated | templates/agents | build/generate_agents.py |
docs/agent-catalog.md | generated | templates/agents | build_all.py (agent-catalog) |
.claude/ | MIXED per subtree, see Facts below | mixed | binplace, template-owned parts only |
templates/skills/*.SKILL.md.tmpl | CANONICAL for all 111 skills' SKILL.md (ADR-108, ADR-109 B3) | itself | renders src/claude/skills/, binplaces .claude/skills/, mirrors src/copilot-cli/skills/ |
src/copilot-cli/{skills,instructions,hooks} | generated | .claude/ trees | build/scripts/build_all.py |
.github/instructions/ | generated | .claude/rules/ | build_all.py (rules) |
scripts/{hook_utilities,github_core,ai_review_common} | CANONICAL for shared Python | itself | n/a |
src/claude/lib/, src/copilot-cli/lib/ | generated direct | scripts/ packages | build_all.py lib step (B5) |
.claude/lib/ | binplaced from src/claude/lib/ | src/claude/lib/ | build_all.py binplace |
src/claude/{agents,rules,hooks,hooks.json,settings.json} | generated (ADR-109 B1, B2, B4; supersedes the pre-ADR-109 hand-synced model) | templates/{agents,rules,hooks}/ | build_all.py, then binplaced to .claude/ |
All 111 skills are template-owned (ADR-108, ADR-109 B3): edit templates/skills/<name>.SKILL.md.tmpl; it renders src/claude/skills/<name>/SKILL.md first, binplace copies that to .claude/skills/<name>/SKILL.md, then the Copilot copy step mirrors it (plus the skill's hand-maintained scripts/, references/, tests/) into src/copilot-cli/skills/<name>/SKILL.md.
Generator inventory inside build/scripts/build_all.py (the GENERATORS list; order is load-bearing per the Order matters comment above it; seven since ADR-064 retired commands):
| # | Generator | Reads | Writes |
|---|---|---|---|
| 1 | agents | templates/agents/*.shared.md + templates/platforms/*.yaml | src/copilot-cli/agents/*.agent.md, src/vs-code-agents/*.agent.md |
| 2 | agent-catalog | templates/agents/*.shared.md | docs/agent-catalog.md |
| 3 | adr-index | the ADR corpus under .project-toolkit/architecture/ | .project-toolkit/architecture/README.md |
| 4 | lib | scripts/ packages | src/claude/lib/, src/copilot-cli/lib/; binplaced .claude/lib/ |
| 5 | skills | .claude/skills/*/SKILL.md (template-owned skills compile first; ADR-108, ADR-109) | src/copilot-cli/skills/ |
| 6 | rules | .claude/rules/*.md | .github/instructions/*.instructions.md AND src/copilot-cli/instructions/ |
| 7 | hooks | .claude/settings.json + .claude/hooks/ | src/copilot-cli/hooks/ + src/copilot-cli/hooks/hooks.json |
Facts that prevent confusion:
build_all.pyenforces a no-write invariant on.claude/(REQ-003-010): if any generator writes there, the run exits 2 withREQ-003-010 VIOLATION, exce