Feature: central MCP + AGENT/AGENTS management with generated outputs

[vincentkoc]

Problem

We have strong skill packaging in this repo, but MCP configuration and AGENT.md/AGENTS.md guidance are still fragmented across machines/repos. This creates drift, duplicated effort, and inconsistent agent behavior.

Proposal

Add a centralized, generated workflow for MCP and agent instruction files, similar to how skills are managed.

1) Central source of truth

Introduce top-level config trees:

• mcps/ for MCP registry + profiles
• agents/ for layered instruction content

Suggested structure:

mcps/
  registry.yaml
  profiles/
    local.yaml
    work.yaml
    ci.yaml
agents/
  base.md
  domain/
    docs.md
    integrations.md
    security.md
  tool/
    codex.md
    cursor.md
  repos/
    <repo>.md

2) Generated outputs (not hand-edited)

Add render/sync scripts that generate final files per target repo/tool:

• AGENTS.md
• AGENT.md
• tool-specific MCP config outputs (Codex/Cursor/other)

3) Secret-safe MCP handling

• Store only env var keys in git (OPENAI_API_KEY, etc.)
• Never commit credentials
• Support local secret injection via shell env/direnv/1Password, etc.

4) Validation and drift checks

Add Make targets and CI checks:

• make mcp-validate
• make agents-validate
• make sync-context REPO=/path/to/repo
• fail CI when generated outputs are stale

5) Dotfiles/bootstrap integration

Enable profile-driven setup from dotfiles/bootstrap:

• pick profile (local/work)
• sync MCP + AGENT docs into selected repos

Deliverables

• mcps/ and agents/ source trees scaffolded
• render/sync scripts for MCP + agent docs
• validation scripts + Make targets
• CI job for generated-file drift
• docs in README for usage and profile selection

Acceptance criteria

• One command can render/sync MCP + AGENT.md/AGENTS.md for a target repo
• No secrets stored in repository files
• CI fails when generated outputs are out of date
• Multi-profile support works (local, work, ci)
• Existing skill workflows remain unchanged

Notes

This aligns .skills with the same philosophy used for skills themselves: composable, versioned, testable artifacts instead of ad-hoc prompt/config sprawl.