Agent Runtime Parity

Use this skill when managing capabilities across multiple AI runtimes to prevent divergence, or when a configuration change, rule update, MCP addition, or credential routing must propagate uniformly to all active AI surfaces.

This skill ensures that team AI tools stay synchronized and that operational changes made in one runtime surface automatically propagate to others—eliminating manual copy-paste sync and the drift that follows.

Core Model

Treat your canonical source repository (e.g., <REPO_ROOT>/skills/, <REPO_ROOT>/rules/) as the single source of truth for cross-agent capabilities.

Active AI Surfaces

Define your active AI surfaces explicitly. Common examples:

• Claude Code (Anthropic)
• Codex / Codex CLI (OpenAI)
• Cursor (VSCode-based, custom LLM integration)
• Gemini / Gemini CLI (Google)
• Custom agent frameworks (LangChain, LlamaIndex, etc.)
• Shared or team-wide agent orchestration tools
• Desktop or CLI agent runners

Tool-Native Adapters

Use tool-native configuration formats rather than converting everything to one format:

• Skill frameworks (SKILL.md, AGENT.md, etc.): store in tool-native directories
• Rules and instructions (.mdc, .txt, .md): store in tool-specific rule folders
• MCP/connector configs (JSON, YAML): use environment variable references instead of hardcoded secrets
• Credential routing notes: document via Bitwarden, vaults, or secure config stores—never commit raw secrets

Example Structure

<REPO_ROOT>/
├── skills/
│   ├── skill-name-1/
│   │   └── SKILL.md
│   └── skill-name-2/
│       └── SKILL.md
├── rules/
│   ├── universal-rule.md
│   └── <tool>-specific-rule.mdc
├── mcp-configs/
│   ├── claude-config.json
│   ├── codex-config.json
│   └── cursor-config.json
└── sync-scripts/
    └── sync-agent-parity.ps1  (or .sh for Unix)

Hard Rule: Propagation Mandate

Any durable operational change made for one AI surface must be propagated to every active AI surface in the same session, or the gap must be documented explicitly.

What Must Propagate

• Global instruction files and rules
• Shared skills, plugins, agents, adapters, and helper scripts
• MCP/connector declarations and configuration templates (using env-var references, not secrets)
• API inventories, credential routing notes, and vault item metadata
• Durable memories, handoff documents, and cross-agent troubleshooting notes
• Environment variable names and their documented purposes

What MUST NOT Propagate

• Raw secrets, API keys, tokens, or passwords
• OAuth tokens, session stores, or browser cookies
• Machine-specific authentication state (mcp-tokens, local auth files)
• Logs, transcripts, caches, or runtime debugging output
• Personal information or team-private data

Safe propagation: use references (env-var names, Bitwarden item IDs, vault paths) instead of values.

Duplicate Avoidance

For universal skills and rules, maintain one canonical source directory in your repository. Do not hand-maintain independent copies in each runtime folder.

Exception: tool-specific adapters (Cursor .mdc rules, tool-native config files) may be generated or adapted from the canonical source, but the source itself should remain singular.

Before syncing into any runtime folder, compare new content against existing content. Never automatically delete or overwrite real directories without inspection.

Sync Workflow

1. Define Your Sync Command

Create a tool-native sync script (PowerShell, Bash, or Python) that:

• Reads from your canonical source directory
• Identifies all active AI surface locations on your machine
• Copies/symlinks rules, skills, and safe configs to each location
• Verifies no raw secrets were copied
• Reports what was synced and any errors

PowerShell example:

powershell
# sync-agent-parity.ps1
param(
    [string]$SourceDir = "C:\path\to\canonical\skills",
    [string[]]$TargetDirs = @(
        "C:\path\to\.claude\skills",
        "C:\path\to\.codex\skills",
        "C:\path\to\.gemini\skills"
    )
)

foreach ($target in $TargetDirs) {
    if (-not (Test-Path $target)) {
        New-Item -ItemType Directory -Path $target -Force | Out-Null
    }
    Copy-Item "$SourceDir\*" $target -Recurse -Force
    Write-Host "Synced to $target"
}

# Verify no raw API keys were copied
Get-ChildItem $TargetDirs -Recurse -File | ForEach-Object {
    $content = Get-Content $_.FullName -Raw
    if ($content -match 'sk-|api_key=|password=') {
        Write-Warning "Possible secret in $($_.FullName)"
    }
}

2. Document Sync Scope

Explicitly list what your sync script manages:

markdown
## Synced Artifacts

- Shared skills: `skills/*/SKILL.md`
- Universal rules: `rules/universal-*.md`
- MCP config templates: `mcp-configs/*.json` (env-var refs only)
- Helper scripts: `scripts/helpers/*.ps1`
- NOT synced: `.env`, Bitwarden vaults, machine-specific configs

3. Run Sync After Changes

Make it a habit:

• After editing a shared skill or rule → run sync
• After adding a new MCP connector → run sync
• After onboarding a new AI tool → add it to target directories and run sync
• After credential rotation → update vault references and run sync

Verification Checklist

After syncing, verify:

• ] All target directories received updated files
• ] No raw API keys or passwords appear in any synced file
• ] All synced configs use environment variable references (e.g., $env:OPENROUTER_API_KEY, ${ANTHROPIC_API_KEY})
• ] MCP JSON configs are valid JSON (test with jq or JSON linter)
• ] Tool-native rule files (.mdc, .rules) have correct syntax for their tool
• ] Bitwarden or credential vault item names are documented (not values)
• ] No broken symlinks or file paths
• ] Each AI tool can still be launched and reaches its configured rules/skills

Common Patterns

Adding a New AI Tool to Your Runtime

1. Identify the new tool's rule/config directory (e.g., C:\Users\username\.newtool\skills)
2. Add it to your sync script's $TargetDirs list
3. Run sync
4. Verify the tool can see its new rules/skills
5. Test with a simple query to confirm parity

Rotating a Credential Across All Tools

1. Generate new credential in the source service
2. Update your credential vault (Bitwarden, .env, AWS Secrets Manager, etc.)
3. Verify the new credential works in one tool first
4. Update all MCP configs and env-var references to point to the new credential name/ID
5. Run sync
6. Test each tool to confirm it uses the new credential
7. Revoke the old credential at source

Debugging Drift

If one AI tool behaves differently than others:

1. Check the tool's local rule/skill directory against the synced version
2. Verify the tool's MCP config and env-var assignments
3. Check for local overrides (e.g., tool-specific .env that shadows the synced version)
4. Review recent manual edits that may not have been synced
5. Run sync again and restart the tool

Troubleshooting

| Problem | Diagnosis | Solution | |---------|-----------|----------| | Tool doesn't see updated rules | Sync ran but tool wasn't restarted | Restart the AI tool or reload its config | | Secret leaked into sync target | Raw credential in a synced file | Rotate credential, remove file, use env-var ref instead | | One tool has different rules than others | Manual local edit not synced | Re-apply edit to canonical source and run sync | | MCP config fails to parse | Invalid JSON in synced config | Validate JSON syntax; check env-var expansion | | Sync script fails | Permission issue or path doesn't exist | Verify paths exist, user has write access, no files locked by running tools |

Related Skills

• MCP-Builder: Create and test custom MCP connectors for your tools
• Tokens-Taxonomy: Organize and rotate credentials across team tools
• Bitwarden-Access: Manage credentials in a shared vault

Notes for Team Leads

If managing AI agent parity across a team:

• Designate one person as parity maintainer (responsible for canonical source and sync runs)
• Document the sync cadence (e.g., "after every merge to main, run sync")
• Use a shared git repo or artifact store for the canonical source
• Audit synced artifacts regularly (quarterly secret scan)
• Train team members to never hand-edit tool-specific copies—all changes go to canonical source

This prevents drift, reduces manual work, and ensures all team members see the same rules and capabilities across all their AI tools.