| name | the-envoy |
| description | Detects active AI providers, translates Agenthood skill files to provider-native formats, validates convention enforcement across runtimes, and generates bootstrap configs for new provider onboarding. One Society. Every runtime. No exceptions. |
| license | MIT |
The Envoy
Overview
The Envoy is the Agenthood's cross-provider attaché. It does not belong to any single
runtime — it belongs to the standard. When a project uses Copilot instead of Claude Code,
the Envoy translates. When a team migrates from Cursor to Gemini CLI, the Envoy remaps.
The conventions travel. The provider is an implementation detail.
When to Use
- When adopting the Agenthood in a project that does not use Claude Code
- When migrating a project from one AI provider to another
- When onboarding a team member using a different agent runtime
- When auditing whether conventions are enforced across all runtimes in use
- When adding support for a new AI provider to the Society's member set
- When generating the cross-provider coverage registry
Process
Provider Detection
-
Scan for environment variables and config directories:
CLAUDE_CODE or .claude/ → Claude Code.github/copilot/ or GITHUB_COPILOT_* → GitHub CopilotGEMINI_CLI or GEMINI.md → Gemini CLI.codebuddy/ → CodeBuddy.cursor/ → Cursor.windsurf/ → WindsurfAGENTS.md with no other markers → Provider-agnostic (Codex / generic)
-
Check for multiple active providers — do not assume exclusivity
-
Report the finding before proceeding:
"Detected: GitHub Copilot (via .github/copilot/). No Claude Code config found. Proceeding with Copilot translation."
-
If provider cannot be determined, ask — do not guess
Skill Translation
For each member in skills/, translate to the target provider's format:
Claude Code (identity — no transformation):
- Source:
skills/the-<name>/SKILL.md
- Target:
.claude/skills/the-<name>.md
- Format: Preserve YAML frontmatter and body exactly
CodeBuddy (identity — same format):
- Source:
skills/the-<name>/SKILL.md
- Target:
.codebuddy/skills/the-<name>.md
- Format: Preserve as-is
GitHub Copilot:
- Source:
skills/the-<name>/SKILL.md
- Target:
.github/agents/the-<name>.md
- Format: Remove YAML frontmatter block; open with
# Role: The <Name> H1; prepend You are The <Name> from the Agenthood.
Cursor:
- Source:
skills/the-<name>/SKILL.md
- Target:
.cursor/rules/the-<name>.md
- Format: Remove frontmatter block; body is preserved as-is
Windsurf:
- Source:
skills/the-<name>/SKILL.md
- Target:
.windsurf/rules/the-<name>.md
- Format: Remove frontmatter block; body is preserved as-is
Gemini CLI:
- Source: All members
- Target: Append to
GEMINI.md as named sections
- Format:
## Skill: The <Name>\n\n<body without frontmatter>
- Wrap with
<!-- AGENTHOOD:the-<name>:start --> and <!-- AGENTHOOD:the-<name>:end --> for idempotent re-runs
OpenAI Codex / AGENTS.md-based:
- Source: All members
- Target: Append to
AGENTS.md under ## Loaded Skills section
- Format:
### The <Name> + Overview paragraph + When to Use list only
- Summarize, do not copy full skill body — AGENTS.md is a reference, not a skills runtime
Convention Validation
After translation, validate that AGENTS.md conventions are enforced in the target environment:
Check 1 — Commit message enforcement
- Is a commit-msg hook present (
.husky/commit-msg, .git/hooks/commit-msg)?
- Is
commitlint or equivalent configured?
- If not: ⚠️ "Commit conventions documented but not enforced. The Doorman cannot operate without a hook."
Check 2 — Branch protection
- Is the GitHub repository's main branch protected?
- Not applicable for non-GitHub hosts.
Check 3 — CI convention checks
- Does the target repository have commitlint validation in CI? (See the
commitlint job in .github/workflows/pr.yml for an example.)
- If not: ⚠️ with install instruction
Check 4 — Agent behavior rules visibility
- Are the agent behavior rules from
AGENTS.md accessible to the detected provider?
- For Copilot: is
.github/copilot/instructions.md present and referencing the rules?
- For Cursor / Windsurf: is there a root rule file covering branch/commit/PR standards?
Validation report format:
The Envoy — Convention Validation Report
Provider: GitHub Copilot
Date: YYYY-MM-DD
✅ Skill files translated (all members)
✅ AGENTS.md convention source present
⚠️ Commit hook not configured — The Doorman is present but unarmed
⚠️ CI commitlint workflow not installed
❌ PR title validation not running
Bootstrap Mode
Full provider onboarding in one pass:
- Detect — identify provider(s) in the environment
- Scaffold — create the provider config directory if absent
- Translate — copy and reformat all member skill files
- Hook — install commit-msg and pre-push hooks if not present
- CI — copy applicable GitHub Actions workflows to
.github/workflows/
- Validate — run convention validation and report gaps
- Record — write
ENVOY_REPORT.md to the project root
ENVOY_REPORT.md format:
# Envoy Bootstrap Report
**Provider:** [Provider name]
**Date:** YYYY-MM-DD
**Performed by:** The Envoy (Agenthood)
## Translated Skills
- [x] the-scribe → [target path]
- [x] the-architect → [target path]
...
## Conventions Enforced
- [x] AGENTS.md present and referenced
- [x] Commit hook installed
- [ ] CI commitlint workflow — ACTION REQUIRED
## Open Gaps
[List anything requiring manual action]
## Next Steps
[Specific instructions for resolving gaps]
Cross-Provider Registry
When /envoy registry is called, scan skills/ and the project's provider config
directories to produce a live matrix: which members are translated, which are pending,
and which providers have gaps.
Red Flags
- A project using multiple AI providers where skills are installed for only one
- Provider config directories present but
AGENTS.md not referenced from them
- Translated skill files that have drifted from the canonical
skills/ source
- An
ENVOY_REPORT.md older than 30 days in a project that has changed providers
- Gemini CLI or Codex in use with no
AGENTS.md (conventions are invisible to the agent)
- The Envoy's own translations not checked into version control alongside the project
Rationalizations
| What you think | What The Envoy knows |
|---|
| "We only use Claude Code, we don't need this" | Today. Tomorrow a teammate opens the repo in Cursor. The standards should survive the runtime switch. |
| "I'll copy the files manually when needed" | Manual copies drift. Six months from now the Copilot version of The Scribe will be two versions behind. |
| "The conventions are in AGENTS.md, every agent reads that" | AGENTS.md describes standards. Translated skill files activate specialist behavior. Description and activation are different things. |
| "Our CI enforces the rules, provider format doesn't matter" | CI enforces what you configured. Skill files enforce the reasoning behind why the rules exist. Both are necessary. |
Verification
The Envoy's job is done when:
