FAQ¶

Do I need all three supported agents?¶

No. Install or connect only the path you use. Claude Code and Codex can share the same portable skills, while Hermes reads the canonical directory directly.

Why are skills and adapters separate?¶

They have different responsibilities:

skills/ contains portable workflow knowledge shared by every supported agent.
adapters/ contains configuration specific to Claude Code, Codex, or Hermes, plus the runtime-neutral global templates under adapters/shared/.

Keeping those layers separate prevents three copies of the same skill from drifting apart.

Should this repository contain `.claude/skills` and `.codex/skills`?¶

No. Claude Code uses .claude/skills for project-local discovery, but that is a consumer location rather than this repository's canonical store. Codex uses .agents/skills for project-local discovery; .codex/skills is not its documented project skill path.

Installers can place skills into each agent's supported discovery location without duplicating their source in Git.

Can Hermes use the new layout directly?¶

Yes. Point skills.external_dirs at the nested canonical directory:

skills:
  external_dirs:
    - /absolute/path/to/skills/skills

Start a new session after changing the path.

Can Hermes edit an external skill directory?¶

Yes, if the process has filesystem write access. External directories are discovery sources, not read-only boundaries. Make shared changes in a separate Git branch or worktree and submit them through review.

A same-named local Hermes skill can take precedence over the shared version.

What does bootstrap do?¶

./scripts/bootstrap.sh installs the shared and selected provider adapter files into $HOME/.claude and/or $HOME/.codex (or environment overrides). It uses staged writes, timestamped backups, and managed-block merges, and rolls back adapter-file and Git configuration changes on failure. --dry-run performs no filesystem, symlink, or Git configuration changes. --install-skills runs npx skills add before that transaction starts, so a later failure does not uninstall skills it already added.

./scripts/install-codex-agents.sh /path/to/project remains the separate project-level helper; it copies adapters/codex/AGENTS.md into the target project as AGENTS.md.

The installer backs up changed files, refuses a foreign global core.hooksPath, and preserves managed blocks written by other tools, such as ….

What is the overlay structure?¶

Use provider-relative paths matching the public adapter tree:

overlay/
├── shared/AGENTS.base.md
├── shared/hooks/...
├── claude/settings.template.json
├── claude/CLAUDE.block.md
└── codex/config.template.toml, hooks.json, agents/...

Only files that exist in the overlay replace their public counterparts before merging. The overlay itself is never copied into this checkout.

Does this repository publish global configuration?¶

It publishes genericized templates, not anyone's configuration. A runtime-neutral instruction base and lifecycle hook scripts live in adapters/shared/; per-runtime settings templates, hook wiring, subagent definitions, and an injectable CLAUDE.md block live in adapters/claude/ and adapters/codex/.

Real personal content—employer conventions, project trust lists, credentialed MCP servers, private skills, machine paths, session or transcript state—remains forbidden here and belongs in a private overlay repository merged at install time. ADR-0001 records why the earlier "no global configuration" boundary was superseded and what stays out.

Where should Claude Code sub-agents live?¶

At runtime they live in your own ~/.claude/agents/, or with the project that owns them. This repository may publish subagent definition templates under adapters/claude/, but only genericized ones: capability-based roles with no employer context, no private tool names, and no pinned personal model versions. A persona tied to one employer, project, or model choice stays in your private overlay.

How do I migrate from the old root-level layout?¶

Hermes recursively discovers nested skills, so an existing repository-root entry remains compatible. Point skills.external_dirs at <checkout>/skills if you want discovery limited to the canonical directory. The Codex installer command stays the same. Reinstall or update skills managed by the skills CLI so recorded source paths follow the new layout.

The old layout's global Claude configuration bundle—one user's real ~/.claude tree—was removed and is not coming back. Its replacement is the genericized template layer under adapters/, which shares none of that content; see ADR-0001.

Can a target project have its own rules?¶

Yes. Keep stack- and domain-specific rules in the target project, such as AGENTS.md, CLAUDE.md, or project-local skills. This repository should remain portable and generic.

bootstrap.sh refuses to merge config.toml with "unrecognized keys" error¶

The Codex bootstrap installer (./scripts/bootstrap.sh --provider codex) now compares the keys in each existing section of your config.toml against the template's declared keys for that section. If it finds keys the template doesn't know about (legacy fields like max_threads from older Codex versions, hand-edited configs, or previously-deprecated names), it refuses to merge and shows:

bootstrap: section [agents] contains unrecognized keys: max_threads. Use --merge-unknown-keys to proceed anyway.

Why? Codex's [agents] table uses serde(flatten) for subtables like [agents.explorer]. When a flattened struct's table also contains keys outside its known field set, serde misreports a valid single-occurrence field as a "duplicate field" error instead of "unknown field". The TOML text is valid, but Codex fails to start.

Fix options:

Manual (recommended): For each legacy key, copy its value to the corresponding new template key before removing the legacy key, then run bootstrap. For example:
max_threads → copy value to max_concurrent_threads_per_session
Then remove the max_threads line
Run bootstrap again
Force merge: Run ./scripts/bootstrap.sh --provider codex --merge-unknown-keys to allow the merge despite unknown keys. The legacy keys will be preserved alongside the new ones (but may cause the false "duplicate field" error in Codex).