# Manage Agent Config

> Manage files under .claude/{skills,agents,rules}/, .agents/{skills,rules}/, or .codex/agents/. Covers dual-tool Claude/Codex layout and reminds to run make sync-agent-config.

- Skill: `miyamura80/manage-agent-config` (Agent Skill)
- Install (CLI): `npx skillmds@latest add miyamura80/manage-agent-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/miyamura80/manage-agent-config/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Miyamura80 (https://skillmd.com/u/miyamura80)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/miyamura80/manage-agent-config

---


# Managing Claude <-> Codex skills and subagents in this repo

This repo is dual-tool. Before you create or edit anything under `.claude/`, `.agents/`, or `.codex/`, read this and the detailed rule at `.claude/rules/codex-claude-sync.md`.

## Decision tree

**Creating a new skill?**

1. Does it need Claude-only features (`allowed-tools`, argument substitutions, shell preprocessing, or Claude-specific interpolations)?
   - **Yes** -> `.claude/skills/<name>/SKILL.md` (real directory, no symlink). Claude-only.
   - **No** -> `.agents/skills/<name>/SKILL.md`. Shared; `make sync-agent-config` creates the `.claude/skills/<name>` symlink.

**Creating a new subagent?**

- Always edit `.claude/agents/<name>.md` (markdown + YAML frontmatter). That is the source of truth.
- `.codex/agents/<name>.toml` is **generated** - never hand-edit.
- Run `make sync-agent-config` - the TOML appears.

**Creating a new path-scoped rule?**

- `.claude/rules/<name>.md` is the **source of truth**. Use `globs:` frontmatter (not `paths:`).
- `.agents/rules/<name>.md` is a symlink mirror, created by `make sync-agent-config`.
- Read the `new-agent-rule` skill before writing your first rule.

**Renaming or deleting?**

- Rename or delete the source file (under `.agents/skills/`, `.claude/agents/`, or `.claude/rules/`).
- Run `make sync-agent-config` - stale symlinks and orphaned TOMLs are pruned automatically.

## Frontmatter rules for shared skills

`.agents/skills/<name>/SKILL.md` must only use:

- `name` (required, lowercase-hyphens, <=64 chars)
- `description` (required, <=250 chars - Codex and Claude use this for implicit matching)
- Plain markdown body

Do **not** use any of these in a shared skill:

- `allowed-tools`, `disable-model-invocation`, `user-invocable`, `context`, `agent`, `model`, `effort`, `hooks`, `paths`, `shell`, `argument-hint`
- `$ARGUMENTS`, `$1`...`$N`, `${CLAUDE_SKILL_DIR}`, `${CLAUDE_SESSION_ID}` substitutions
- Backtick-bang shell preprocessing or fenced shell-preprocessing blocks

All of those are Claude-only. In Codex they pass through literally and confuse the model. If you need them, make the skill Claude-only (see decision tree above).

## Subagent format notes

Claude `.md` frontmatter keys that don't exist in Codex (`tools`, `model`, `color`) are preserved as TOML comments in the generated `.codex/agents/<name>.toml` for human reference. They do not affect Codex behavior. If tool restrictions matter to the agent's job, describe them in the prose body so both tools read them.

## After any change

Always run `make sync-agent-config`. The prek pre-commit hook will block the commit otherwise. The script is idempotent and silent when there's nothing to do.