feat: ship managed MEX agent skills

[theDakshJaitly]

Summary

• Package the official mex-inbox and mex-relay skills in the npm artifact and install them through normal mex setup for Claude Code, Codex, or both.
• Add reusable, ownership-aware managed installation with atomic install/update behavior, modified/unmanaged conflict preservation, dry-run reporting, Git-ignore diagnostics, and client-aware managed instruction blocks.
• Add mex skills sync, including --dry-run, --json, and optional repeatable --tool selection.
• Add bounded Inbox/Relay action-contract discovery so routine agent workflows do not emit the complete capability catalogs.
• Update maintained templates, dogfood surfaces, setup documentation, CLI help, release notes, and packed-package smoke coverage.

Safety and compatibility

• Plain npm install ships the payload but does not mutate the consuming repository; there is no install/postinstall mutation.
• Existing user-authored instructions outside the managed block and unrelated skills are preserved.
• Modified managed skills, unmanaged same-name skills, malformed metadata/markers, symlink paths, and traversal attempts fail closed.
• Local drafts remain checkout-only; canonical MEX writes remain working-tree changes requiring a separate commit/push.
• No automatic staging, commits, pushes, pulls, notifications, plugins, MCP tools, hooks, or Hub UI changes.
• No new runtime dependency or lockfile change.

Validation

• skill-creator validation: both skills passed.
• Focused installer/setup/content/CLI tests: 93/93 passed.
• Timeout-only integration files rerun in isolation: 127/127 passed.
• npm run typecheck: passed.
• npm run build: passed.
• npm run test:hub:package: passed against the real packed tarball, including ordinary install no-mutation, interactive setup, exact deployed bytes/sidecars, and sync idempotence.
• Full suite under concurrent I/O: 2,916/2,941 passed; all 25 failures were fixed-duration timeouts in four files, and those exact files subsequently passed 127/127 in isolation.
• Simulated merge into integration/human-team-memory-v1: clean.

[Copilot]

🟡 Changes recommended

The focused Inbox --action contract payload is missing an existing enforced/advertised request-size limit field, making the new contract output incomplete for API consumers.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds first-class, managed installation of the official mex-inbox and mex-relay agent skills to the mex-agent npm package and wires them into mex setup and a new mex skills sync command, while also introducing bounded --action contract discovery for Inbox/Relay to avoid emitting full catalogs during routine agent workflows.

Changes:

• Ship the official skill trees in the npm artifact and add managed install/sync flows (mex setup + mex skills sync) with conflict preservation and dry-run reporting.
• Add bounded contract discovery for Inbox/Relay via mex inbox|relay contract --action <command-id> --json.
• Update templates, docs, smoke coverage, and tests to validate packaging + idempotence + non-mutation guarantees.

File summaries

File	Description
test/wiki-architecture.test.ts	Whitelist installer file in scoped-write test
test/tool-config-templates.test.ts	Validate client-aware managed blocks in templates
test/cli.test.ts	Add CLI JSON error + action-contract size assertions
test/capabilities.test.ts	Mark skills as telemetry/first-run exempt
test/agent-skills-content.test.ts	New: validate packaged skill content/frontmatter
templates/SETUP.md	Document mex setup + mex skills sync
templates/AGENTS.md	Update guidance + add MEX context policy block
templates/agent-memory/AGENTS.md	Same as templates/AGENTS.md for agent-memory
templates/.tool-configs/README.md	Update manual/setup guidance for skills + blocks
templates/.tool-configs/copilot-instructions.md	Update bounded-resolver guidance text
templates/.tool-configs/CLAUDE.md	Add managed skill block section for Claude template
templates/.tool-configs/.windsurfrules	Update bounded-resolver guidance text
templates/.tool-configs/.cursorrules	Update bounded-resolver guidance text
src/team/relay/cli/index.ts	Export new action-contract helpers/types
src/team/relay/cli/contract.ts	Add --action support + tightened output/limits
src/team/relay/cli/contract-catalog.ts	Add action-scoped contracts + schema projection
src/team/relay/cli/builder.ts	Add --action flag to relay contract command
src/team/relay/cli/tests/contract.test.ts	Test action-scoped relay schema closures
src/team/inbox/cli/contract.ts	Add --action support + tightened output/limits
src/team/inbox/cli/builder.ts	Add --action flag to inbox contract command
src/team/inbox/cli/tests/contract.test.ts	Test action-scoped inbox schema closures
src/team/cli/contract-projection.ts	New: build focused schema closure from $defs
src/setup/index.ts	Install managed skills/blocks during mex setup
src/setup/tests/agent-skills.test.ts	New: setup seam tests for skill install/dry-run
src/cli.ts	Add mex skills sync command + JSON parse envelope
src/capabilities.ts	Add inbox action contracts + reusable constraints
src/agent-skills/types.ts	New: types for managed skill install/sync reporting
src/agent-skills/report.ts	New: bounded managed-block diff rendering
src/agent-skills/instructions.ts	New: marker-delimited managed instruction blocks
src/agent-skills/index.ts	New: public exports for agent-skills subsystem
src/agent-skills/tests/instructions.test.ts	New: managed instruction block behavior tests
src/agent-skills/tests/installer.test.ts	New: extensive atomic installer/sync test suite
skills/mex-relay/SKILL.md	New: canonical mex-relay skill content
skills/mex-relay/references/cli-workflows.md	New: relay bounded contract workflow guide
skills/mex-relay/agents/openai.yaml	New: OpenAI agent metadata for relay skill
skills/mex-inbox/SKILL.md	New: canonical mex-inbox skill content
skills/mex-inbox/references/cli-workflows.md	New: inbox bounded contract workflow guide
skills/mex-inbox/agents/openai.yaml	New: OpenAI agent metadata for inbox skill
scripts/hub-pack-smoke.mjs	Extend packed smoke to validate skills + non-mutation
README.md	Document official skills + setup/sync behavior
package.json	Include skills/ in published package files
docs/vim-neovim.md	Update setup instructions + skill usage guidance
CLAUDE.md	Replace root content with managed skills block
CHANGELOG.md	Add release notes for managed skills + action contracts
AGENTS.md	New: managed skills block for Codex root anchor
.mex/SETUP.md	Mirror templates/SETUP.md updates
.mex/ROUTER.md	Update approval/confirmation policy wording
.mex/config.json	Record configured aiTools (claude, codex)
.mex/AGENTS.md	Update guidance + add MEX context policy block
.mex/.tool-configs/copilot-instructions.md	Update bounded-resolver guidance text
.mex/.tool-configs/CLAUDE.md	Add managed skill block section for maintained Claude
.mex/.tool-configs/.windsurfrules	Update bounded-resolver guidance text
.mex/.tool-configs/.cursorrules	Update bounded-resolver guidance text
.gitignore	Allow committing only official .claude/skills/mex-*
.claude/skills/mex-relay/SKILL.md	New: repo dogfood managed Claude skill copy
.claude/skills/mex-relay/references/cli-workflows.md	New: dogfood relay reference copy
.claude/skills/mex-relay/agents/openai.yaml	New: dogfood relay OpenAI metadata copy
.claude/skills/mex-relay/.mex-managed.json	New: ownership sidecar for managed relay skill
.claude/skills/mex-inbox/SKILL.md	New: repo dogfood managed Claude skill copy
.claude/skills/mex-inbox/references/cli-workflows.md	New: dogfood inbox reference copy
.claude/skills/mex-inbox/agents/openai.yaml	New: dogfood inbox OpenAI metadata copy
.claude/skills/mex-inbox/.mex-managed.json	New: ownership sidecar for managed inbox skill
.agents/skills/mex-relay/SKILL.md	New: repo dogfood managed Codex skill copy
.agents/skills/mex-relay/references/cli-workflows.md	New: dogfood relay reference copy (Codex)
.agents/skills/mex-relay/agents/openai.yaml	New: dogfood relay OpenAI metadata copy (Codex)
.agents/skills/mex-relay/.mex-managed.json	New: ownership sidecar for managed relay skill (Codex)
.agents/skills/mex-inbox/SKILL.md	New: repo dogfood managed Codex inbox skill copy
.agents/skills/mex-inbox/references/cli-workflows.md	New: dogfood inbox reference copy (Codex)
.agents/skills/mex-inbox/agents/openai.yaml	New: dogfood inbox OpenAI metadata copy (Codex)
.agents/skills/mex-inbox/.mex-managed.json	New: ownership sidecar for managed inbox skill (Codex)

Review details

Suppressed comments (1)

src/capabilities.ts:2196

• The focused Inbox action contract payload doesn’t include the portable spec-request byte limit (maxPortableSpecRequestBytes), even though the runtime enforces TEAM_INBOX_SPEC_LIMITS.maxPortableRequestBytes and the full Inbox contract advertises it. This makes the --action contract’s requestFile limits incomplete for clients relying on it to build valid request files.

• Files reviewed: 70/71 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.