Sync Agent Infrastructure
Detect and fix drift across the agent-first infrastructure files. These files reference each other and must stay consistent:
| File |
What it tracks |
AGENTS.md |
Project identity, workflow chains, architecture overview, issue/PR conventions, skill maintenance pointer |
CONTRIBUTING.md |
Skills table, workflow chains, "When to Open an Issue" guidance, skill references |
CONTRIBUTING.md issue lifecycle section |
Human-facing issue states, roadmap decisions, acceptance signals, and direct-versus-queued agent ownership |
README.md |
"Use OpenShell with Your Agent" and "Built With Agents" sections |
.github/ISSUE_TEMPLATE/bug_report.yml |
Skill name references in diagnostic guidance |
.github/ISSUE_TEMPLATE/feature_request.yml |
Skill name references in investigation guidance |
.github/ISSUE_TEMPLATE/config.yml |
Contact link text referencing skills |
.github/workflows/issue-triage.yml |
Comment text referencing skills |
.agents/skills/triage-issue/SKILL.md |
Skill name references in gate check and diagnosis steps |
skills/*/SKILL.md |
Standalone user instructions and links to documentation, included files, and related skills |
.agents/skills/create-github-pr/SKILL.md |
Pre-PR agent infrastructure check |
.agents/skills/review-github-pr/SKILL.md |
Review-time agent infrastructure check |
.agents/skills/build-from-issue/SKILL.md |
Label awareness and pre-commit agent infrastructure check |
.claude/agents/principal-engineer-reviewer.md |
Shared review-time agent infrastructure check |
When to Run
- After adding, removing, renaming, or moving a skill in
skills/ or .agents/skills/
- After adding, removing, or renaming a crate in
crates/
- After changing workflow chain relationships between skills
- After changing which product or development areas a skill covers
- After modifying issue or PR templates
- Before opening a PR that touches any of the above
Skill Maintenance Map
Use this map when product behavior, commands, or development workflows change. It is a routing aid, not an exhaustive dependency list. Search both skills/ and .agents/skills/ for the changed command, field, component, or workflow before concluding that no other skill needs an update.
| Change area |
Skills to review |
| CLI commands, flags, defaults, or workflows |
openshell-cli |
| Sandbox policy schema, presets, or enforcement behavior |
generate-sandbox-policy, openshell-cli |
| Supervisor middleware policy, registrations, runtime, or failure behavior |
generate-sandbox-policy, openshell-cli, debug-openshell-cluster |
| Gateway deployment, Helm, runtime drivers, or health checks |
debug-openshell-cluster, helm-dev-environment |
Inference routing, providers, or inference.local behavior |
debug-inference, openshell-cli |
| TUI architecture, navigation, data fetching, or UX |
tui-development |
| Release artifacts or post-publish smoke coverage |
test-release-canary |
| GitHub Actions workflows, required checks, or CI diagnostics |
watch-github-actions; also test-release-canary for release smoke coverage |
| Gator harness, sandbox image, supervision, or model overrides |
launch-openshell-gator |
| SBOM generation, dependency metadata, or license workflows |
sbom |
| Issue templates, labels, contribution gates, or spike/build workflow |
triage-issue, create-spike, build-from-issue, create-github-issue |
| PR template, review conventions, or vouch behavior |
create-github-pr, review-github-pr, build-from-issue |
| Security review or remediation workflow |
review-security-issue, fix-security-issue |
| RFC template, numbering, or lifecycle |
create-rfc |
| Documentation structure, navigation, or doc-update workflow |
update-docs-from-commits |
| Skills, crates, workflow chains, issue/PR templates, or agent cross-references |
sync-agent-infra |
Prerequisites
You must be in the OpenShell repository root.
Step 1: Inventory Current State
Gather the source of truth for each category.
Skills
List public and contributor skill directories separately:
ls -1 skills/
ls -1 .agents/skills/
The directories are canonical by audience: skills/ contains public, installable user/operator skills and .agents/skills/ contains internal contributor workflows. Every other file must agree with both inventories.
Crates
List all crate directories:
ls -1 crates/
Workflow Chains
The canonical workflow chains are defined in AGENTS.md under "## Workflow Chains". Read that section — it is the source of truth for skill pipelines.
Labels
The canonical label set is used by skills and templates. The key labels are: state:triage-needed, state:needs-info, state:validated, state:accepted, agent:plan-requested, agent:plan-ready, agent:implementation-requested, agent:in-progress, agent:pr-opened, roadmap, topic:security, good first issue, help wanted, spike, and the relevant area:*, topic:*, integration:*, and test:* labels. Lifecycle and agent:* request labels gate unattended queue pickup. They do not prevent a direct user request: the agent warns about each missing or incomplete expected workflow label and continues with the requested phase without changing those labels.
Step 2: Check Each File for Drift
For each file in the table above, check for the following inconsistencies:
CONTRIBUTING.md
- Public skills table — Every skill in
skills/ must appear in "Skills for Using OpenShell" and no contributor skill may appear there.
- Contributor skills table — Every skill in
.agents/skills/ must appear in "Agent Skills for Contributors" and no public skill may appear there.
- Inventory paths — No skill in either table should reference a directory that does not exist.
- Workflow chains — Must match
AGENTS.md workflow chains exactly.
- Skill references in prose — Any named skill must exist in exactly one canonical skill directory.
AGENTS.md
- Architecture overview — Every crate in
crates/ must appear in the architecture table. The python/, proto/, deploy/, .agents/ rows must also be present.
- Skill layout — The architecture table must contain separate
skills/ and .agents/skills/ rows with accurate audience descriptions.
- Workflow chains — Verify each skill named in a chain exists in exactly one of the two skill directories.
- Issue/PR conventions — Verify referenced skills (
create-github-issue, create-github-pr, build-from-issue) exist.
- Skill maintenance pointer — Verify it still points to
sync-agent-infra and does not duplicate the maintenance map from this skill.
Issue Lifecycle Documentation
CONTRIBUTING.md issue lifecycle section — State, roadmap, acceptance-signal, and agent-workflow meanings must match AGENTS.md.
- Invocation modes — Lifecycle and
agent:* request labels must gate unattended queue pickup without blocking a direct user request to a specific agent.
- Direct-mode warnings — Guidance must require the agent to warn about each missing or incomplete expected workflow label, continue with the requested phase, and leave labels unchanged.
README.md
- Public installation guidance — The README must distinguish
skills/ from .agents/skills/, include npx skills add NVIDIA/OpenShell, and list only canonical public skills as installable.
- "Built With Agents" — Contributor skill names must exist under
.agents/skills/. Workflow descriptions should be consistent with AGENTS.md chains.
Issue Templates
bug_report.yml — Must collect a User Story, Problem Statement, Impact / Why This Matters, Acceptance Criteria, Reproduction Steps, and Environment. Logs are optional and bug-specific; reporter diagnostics must not be required.
feature_request.yml — Must collect a User Story, Problem Statement, Impact / Why This Matters, Proposed Design, Acceptance Criteria, and Alternatives Considered. The design describes workflow and observable behavior without prescribing internal implementation; agent investigation is optional.
config.yml — Skill category descriptions in contact links should be accurate.
Issue Triage Workflow
issue-triage.yml — Skill names in the redirect comment must exist.
Skill Cross-References
triage-issue — Skills referenced in gate check and diagnosis steps must exist.
openshell-cli — Companion skills table entries must exist in one canonical location.
build-from-issue — Label names must match the project's label taxonomy. Lifecycle and request labels must gate unattended queue pickup, while direct requests warn on workflow discrepancies and continue.
create-spike — Reference to build-from-issue as next step must be accurate.
review-security-issue / fix-security-issue — Cross-references between the two must be accurate.
- PR creation and review checks — The
create-github-pr, review-github-pr, build-from-issue, and principal-engineer-reviewer references to sync-agent-infra must exist and use trigger conditions aligned with this skill.
Skill Layout, Metadata, and Portability
- Placement — The four public skills (
openshell-cli, generate-sandbox-policy, debug-inference, and debug-openshell-cluster) must live only in skills/. Every other repository skill must live only in .agents/skills/.
- Internal metadata — Every
.agents/skills/*/SKILL.md must set metadata.internal: true. Public skills must not set internal metadata. Treat this as a discovery filter, not an access-control boundary.
- Unique names — Parse the
name field from every SKILL.md under both roots. Every name must be globally unique and match the documented inventory.
- Local references — Every relative Markdown link and referenced file in a skill must resolve within that installed skill directory unless the reference is an explicit published URL.
- Canonical paths — Contributor skills that name the source location of a public skill must use
skills/<name>/..., never .agents/skills/<name>/....
- Public portability — Public skills must not require repository-relative files under
docs/, architecture/, crates/, deploy/, or .agents/; source builds; mise; or repository E2E workflows. Use installed openshell --help for command syntax and Markdown endpoints under https://docs.nvidia.com/openshell/latest/ (URLs ending in .md) for product documentation.
- No canonical documentation copies — Review public reference files and large command/schema blocks. Remove material that merely copies CLI help, policy schemas, architecture docs, or published operational documentation; retain only skill-specific reasoning and worked interactions.
- Discovery — Run
npx -y skills add . --list from a clean checkout or disposable copy. It must list exactly the four public skills. Remove any generated lock file or installed directory after the check.
Step 3: Report Drift
If any inconsistencies are found, report them in a structured format:
## Agent Infrastructure Drift Report
### Skills Inventory
- PUBLIC ADDED (exists in skills/ but missing from CONTRIBUTING.md): <list>
- PUBLIC REMOVED (documented as public but missing from skills/): <list>
- CONTRIBUTOR ADDED (exists in .agents/skills/ but missing from CONTRIBUTING.md): <list>
- CONTRIBUTOR REMOVED (documented as contributor but missing from .agents/skills/): <list>
- METADATA/PATH/NAME ERRORS: <list>
- OK: <public count> public and <contributor count> contributor skills consistent
### Architecture Table
- ADDED (exists in crates/ but missing from AGENTS.md): <list>
- REMOVED (in AGENTS.md but missing from crates/): <list>
- OK: <count> components consistent
### Workflow Chains
- STALE: <chain name> references non-existent skill <skill>
- OK: <count> chains consistent
### Cross-References
- <file>:<line> references non-existent skill <skill>
- <file>:<line> references non-existent label <label>
- The skill maintenance map has a stale or missing change-area mapping: <details>
- OK: <count> references consistent
If no drift is found, report: "Agent infrastructure is consistent. No drift detected."
Step 4: Fix Drift
If drift is found, fix it by updating the affected files:
- Added skill — Add it to the CONTRIBUTING.md skills table in the appropriate category. If it participates in a workflow chain, update the chains in both
AGENTS.md and CONTRIBUTING.md.
- Removed skill — Remove it from all files. Check for references in templates and other skills.
- Renamed skill — Update every reference across all files.
- Added crate — Add a row to the AGENTS.md architecture table.
- Removed crate — Remove the row from the AGENTS.md architecture table.
- Changed workflow chain — Update chains in both
AGENTS.md and CONTRIBUTING.md. Update the "Built With Agents" section in README.md if the change is user-visible.
- Changed skill coverage — Update the skill maintenance map in this file and any affected cross-references or companion-skill tables.
- Audience or portability drift — Move the skill to its canonical root, fix internal metadata, replace stale public-skill paths, repair local links, and replace copied product documentation with CLI self-discovery or published documentation links.
After fixing, re-run Step 2 to verify consistency.
Step 5: Summarize Changes
Report what was fixed:
## Changes Made
- Updated CONTRIBUTING.md skills table: added `<skill>`
- Updated AGENTS.md architecture table: removed `<crate>`
- Fixed cross-reference in `.agents/skills/triage-issue/SKILL.md`: `<old>` → `<new>`
1---2name: sync-agent-infra-23description: Detect and fix drift across agent-first infrastructure files. Ensures skill inventories, workflow chains, architecture tables, issue/PR templates, and cross-references stay consistent when skills, crates, or workflows change. Run after adding, removing, or renaming skills or components. Trigger keywords - sync agent infra, sync skills, update agent docs, check agent consistency, agent infra drift, sync contributing, sync agents.4metadata:5 source: https://skillmd.com/skills/nvidia/sync-agent-infra-26 internal: true7---89# Sync Agent Infrastructure1011Detect and fix drift across the agent-first infrastructure files. These files reference each other and must stay consistent:1213| File | What it tracks |14|------|---------------|15| `AGENTS.md` | Project identity, workflow chains, architecture overview, issue/PR conventions, skill maintenance pointer |16| `CONTRIBUTING.md` | Skills table, workflow chains, "When to Open an Issue" guidance, skill references |17| `CONTRIBUTING.md` issue lifecycle section | Human-facing issue states, roadmap decisions, acceptance signals, and direct-versus-queued agent ownership |18| `README.md` | "Use OpenShell with Your Agent" and "Built With Agents" sections |19| `.github/ISSUE_TEMPLATE/bug_report.yml` | Skill name references in diagnostic guidance |20| `.github/ISSUE_TEMPLATE/feature_request.yml` | Skill name references in investigation guidance |21| `.github/ISSUE_TEMPLATE/config.yml` | Contact link text referencing skills |22| `.github/workflows/issue-triage.yml` | Comment text referencing skills |23| `.agents/skills/triage-issue/SKILL.md` | Skill name references in gate check and diagnosis steps |24| `skills/*/SKILL.md` | Standalone user instructions and links to documentation, included files, and related skills |25| `.agents/skills/create-github-pr/SKILL.md` | Pre-PR agent infrastructure check |26| `.agents/skills/review-github-pr/SKILL.md` | Review-time agent infrastructure check |27| `.agents/skills/build-from-issue/SKILL.md` | Label awareness and pre-commit agent infrastructure check |28| `.claude/agents/principal-engineer-reviewer.md` | Shared review-time agent infrastructure check |2930## When to Run3132- After adding, removing, renaming, or moving a skill in `skills/` or `.agents/skills/`33- After adding, removing, or renaming a crate in `crates/`34- After changing workflow chain relationships between skills35- After changing which product or development areas a skill covers36- After modifying issue or PR templates37- Before opening a PR that touches any of the above3839## Skill Maintenance Map4041Use this map when product behavior, commands, or development workflows change. It is a routing aid, not an exhaustive dependency list. Search both `skills/` and `.agents/skills/` for the changed command, field, component, or workflow before concluding that no other skill needs an update.4243| Change area | Skills to review |44|---|---|45| CLI commands, flags, defaults, or workflows | `openshell-cli` |46| Sandbox policy schema, presets, or enforcement behavior | `generate-sandbox-policy`, `openshell-cli` |47| Supervisor middleware policy, registrations, runtime, or failure behavior | `generate-sandbox-policy`, `openshell-cli`, `debug-openshell-cluster` |48| Gateway deployment, Helm, runtime drivers, or health checks | `debug-openshell-cluster`, `helm-dev-environment` |49| Inference routing, providers, or `inference.local` behavior | `debug-inference`, `openshell-cli` |50| TUI architecture, navigation, data fetching, or UX | `tui-development` |51| Release artifacts or post-publish smoke coverage | `test-release-canary` |52| GitHub Actions workflows, required checks, or CI diagnostics | `watch-github-actions`; also `test-release-canary` for release smoke coverage |53| Gator harness, sandbox image, supervision, or model overrides | `launch-openshell-gator` |54| SBOM generation, dependency metadata, or license workflows | `sbom` |55| Issue templates, labels, contribution gates, or spike/build workflow | `triage-issue`, `create-spike`, `build-from-issue`, `create-github-issue` |56| PR template, review conventions, or vouch behavior | `create-github-pr`, `review-github-pr`, `build-from-issue` |57| Security review or remediation workflow | `review-security-issue`, `fix-security-issue` |58| RFC template, numbering, or lifecycle | `create-rfc` |59| Documentation structure, navigation, or doc-update workflow | `update-docs-from-commits` |60| Skills, crates, workflow chains, issue/PR templates, or agent cross-references | `sync-agent-infra` |6162## Prerequisites6364You must be in the OpenShell repository root.6566## Step 1: Inventory Current State6768Gather the source of truth for each category.6970### Skills7172List public and contributor skill directories separately:7374```bash75ls -1 skills/76ls -1 .agents/skills/77```7879The directories are canonical by audience: `skills/` contains public, installable user/operator skills and `.agents/skills/` contains internal contributor workflows. Every other file must agree with both inventories.8081### Crates8283List all crate directories:8485```bash86ls -1 crates/87```8889### Workflow Chains9091The canonical workflow chains are defined in `AGENTS.md` under "## Workflow Chains". Read that section — it is the source of truth for skill pipelines.9293### Labels9495The canonical label set is used by skills and templates. The key labels are: `state:triage-needed`, `state:needs-info`, `state:validated`, `state:accepted`, `agent:plan-requested`, `agent:plan-ready`, `agent:implementation-requested`, `agent:in-progress`, `agent:pr-opened`, `roadmap`, `topic:security`, `good first issue`, `help wanted`, `spike`, and the relevant `area:*`, `topic:*`, `integration:*`, and `test:*` labels. Lifecycle and `agent:*` request labels gate unattended queue pickup. They do not prevent a direct user request: the agent warns about each missing or incomplete expected workflow label and continues with the requested phase without changing those labels.9697## Step 2: Check Each File for Drift9899For each file in the table above, check for the following inconsistencies:100101### `CONTRIBUTING.md`1021031. **Public skills table** — Every skill in `skills/` must appear in "Skills for Using OpenShell" and no contributor skill may appear there.1042. **Contributor skills table** — Every skill in `.agents/skills/` must appear in "Agent Skills for Contributors" and no public skill may appear there.1053. **Inventory paths** — No skill in either table should reference a directory that does not exist.1064. **Workflow chains** — Must match `AGENTS.md` workflow chains exactly.1075. **Skill references in prose** — Any named skill must exist in exactly one canonical skill directory.108109### `AGENTS.md`1101111. **Architecture overview** — Every crate in `crates/` must appear in the architecture table. The `python/`, `proto/`, `deploy/`, `.agents/` rows must also be present.1122. **Skill layout** — The architecture table must contain separate `skills/` and `.agents/skills/` rows with accurate audience descriptions.1133. **Workflow chains** — Verify each skill named in a chain exists in exactly one of the two skill directories.1144. **Issue/PR conventions** — Verify referenced skills (`create-github-issue`, `create-github-pr`, `build-from-issue`) exist.1155. **Skill maintenance pointer** — Verify it still points to `sync-agent-infra` and does not duplicate the maintenance map from this skill.116117### Issue Lifecycle Documentation1181191. **`CONTRIBUTING.md` issue lifecycle section** — State, roadmap, acceptance-signal, and agent-workflow meanings must match `AGENTS.md`.1202. **Invocation modes** — Lifecycle and `agent:*` request labels must gate unattended queue pickup without blocking a direct user request to a specific agent.1213. **Direct-mode warnings** — Guidance must require the agent to warn about each missing or incomplete expected workflow label, continue with the requested phase, and leave labels unchanged.122123### `README.md`1241251. **Public installation guidance** — The README must distinguish `skills/` from `.agents/skills/`, include `npx skills add NVIDIA/OpenShell`, and list only canonical public skills as installable.1262. **"Built With Agents"** — Contributor skill names must exist under `.agents/skills/`. Workflow descriptions should be consistent with `AGENTS.md` chains.127128### Issue Templates1291301. **`bug_report.yml`** — Must collect a User Story, Problem Statement, Impact / Why This Matters, Acceptance Criteria, Reproduction Steps, and Environment. Logs are optional and bug-specific; reporter diagnostics must not be required.1312. **`feature_request.yml`** — Must collect a User Story, Problem Statement, Impact / Why This Matters, Proposed Design, Acceptance Criteria, and Alternatives Considered. The design describes workflow and observable behavior without prescribing internal implementation; agent investigation is optional.1323. **`config.yml`** — Skill category descriptions in contact links should be accurate.133134### Issue Triage Workflow1351361. **`issue-triage.yml`** — Skill names in the redirect comment must exist.137138### Skill Cross-References1391401. **`triage-issue`** — Skills referenced in gate check and diagnosis steps must exist.1412. **`openshell-cli`** — Companion skills table entries must exist in one canonical location.1423. **`build-from-issue`** — Label names must match the project's label taxonomy. Lifecycle and request labels must gate unattended queue pickup, while direct requests warn on workflow discrepancies and continue.1434. **`create-spike`** — Reference to `build-from-issue` as next step must be accurate.1445. **`review-security-issue`** / **`fix-security-issue`** — Cross-references between the two must be accurate.1456. **PR creation and review checks** — The `create-github-pr`, `review-github-pr`, `build-from-issue`, and `principal-engineer-reviewer` references to `sync-agent-infra` must exist and use trigger conditions aligned with this skill.146147### Skill Layout, Metadata, and Portability1481491. **Placement** — The four public skills (`openshell-cli`, `generate-sandbox-policy`, `debug-inference`, and `debug-openshell-cluster`) must live only in `skills/`. Every other repository skill must live only in `.agents/skills/`.1502. **Internal metadata** — Every `.agents/skills/*/SKILL.md` must set `metadata.internal: true`. Public skills must not set internal metadata. Treat this as a discovery filter, not an access-control boundary.1513. **Unique names** — Parse the `name` field from every `SKILL.md` under both roots. Every name must be globally unique and match the documented inventory.1524. **Local references** — Every relative Markdown link and referenced file in a skill must resolve within that installed skill directory unless the reference is an explicit published URL.1535. **Canonical paths** — Contributor skills that name the source location of a public skill must use `skills/<name>/...`, never `.agents/skills/<name>/...`.1546. **Public portability** — Public skills must not require repository-relative files under `docs/`, `architecture/`, `crates/`, `deploy/`, or `.agents/`; source builds; `mise`; or repository E2E workflows. Use installed `openshell --help` for command syntax and Markdown endpoints under `https://docs.nvidia.com/openshell/latest/` (URLs ending in `.md`) for product documentation.1557. **No canonical documentation copies** — Review public reference files and large command/schema blocks. Remove material that merely copies CLI help, policy schemas, architecture docs, or published operational documentation; retain only skill-specific reasoning and worked interactions.1568. **Discovery** — Run `npx -y skills add . --list` from a clean checkout or disposable copy. It must list exactly the four public skills. Remove any generated lock file or installed directory after the check.157158## Step 3: Report Drift159160If any inconsistencies are found, report them in a structured format:161162```markdown163## Agent Infrastructure Drift Report164165### Skills Inventory166- PUBLIC ADDED (exists in skills/ but missing from CONTRIBUTING.md): <list>167- PUBLIC REMOVED (documented as public but missing from skills/): <list>168- CONTRIBUTOR ADDED (exists in .agents/skills/ but missing from CONTRIBUTING.md): <list>169- CONTRIBUTOR REMOVED (documented as contributor but missing from .agents/skills/): <list>170- METADATA/PATH/NAME ERRORS: <list>171- OK: <public count> public and <contributor count> contributor skills consistent172173### Architecture Table174- ADDED (exists in crates/ but missing from AGENTS.md): <list>175- REMOVED (in AGENTS.md but missing from crates/): <list>176- OK: <count> components consistent177178### Workflow Chains179- STALE: <chain name> references non-existent skill <skill>180- OK: <count> chains consistent181182### Cross-References183- <file>:<line> references non-existent skill <skill>184- <file>:<line> references non-existent label <label>185- The skill maintenance map has a stale or missing change-area mapping: <details>186- OK: <count> references consistent187```188189If no drift is found, report: "Agent infrastructure is consistent. No drift detected."190191## Step 4: Fix Drift192193If drift is found, fix it by updating the affected files:1941951. **Added skill** — Add it to the CONTRIBUTING.md skills table in the appropriate category. If it participates in a workflow chain, update the chains in both `AGENTS.md` and `CONTRIBUTING.md`.1962. **Removed skill** — Remove it from all files. Check for references in templates and other skills.1973. **Renamed skill** — Update every reference across all files.1984. **Added crate** — Add a row to the AGENTS.md architecture table.1995. **Removed crate** — Remove the row from the AGENTS.md architecture table.2006. **Changed workflow chain** — Update chains in both `AGENTS.md` and `CONTRIBUTING.md`. Update the "Built With Agents" section in `README.md` if the change is user-visible.2017. **Changed skill coverage** — Update the skill maintenance map in this file and any affected cross-references or companion-skill tables.2028. **Audience or portability drift** — Move the skill to its canonical root, fix internal metadata, replace stale public-skill paths, repair local links, and replace copied product documentation with CLI self-discovery or published documentation links.203204After fixing, re-run Step 2 to verify consistency.205206## Step 5: Summarize Changes207208Report what was fixed:209210```markdown211## Changes Made212- Updated CONTRIBUTING.md skills table: added `<skill>`213- Updated AGENTS.md architecture table: removed `<crate>`214- Fixed cross-reference in `.agents/skills/triage-issue/SKILL.md`: `<old>` → `<new>`215```