Unified configuration for Claude Code, Codex CLI, Cursor, and other agents from a single prompt-guide.yml.
Install globally, initialize a project, then sync tool-specific files (rules, skills, subagents, hooks). Uses a layered layout: short shared AGENTS.md, tool-specific overlays, and a manifest for drift detection.
npm install -g @pelagornis/prompt-guide
prompt-guide init
prompt-guide sync- Overview
- Architecture
- Quick Start
- CLI commands
- Configuration
- Generated files
- Example sandbox
- Monorepo development
- License
prompt-guide reads one source file — prompt-guide.yml — normalizes it through a shared render pipeline, then generates per-tool outputs:
| Tool | Outputs |
|---|---|
| Shared (generic) | AGENTS.md — canonical baseline for Codex, Cursor, Copilot, Gemini CLI, etc. |
| Claude Code | CLAUDE.md (@AGENTS.md), .claude/settings.json, .claude/rules/, .claude/agents/, .claude/skills/, hooks |
| Codex | .codex/instructions/, .codex/config.toml (points at root AGENTS.md; no duplicate AGENTS.md) |
| Cursor | .cursor/rules/*.mdc (glob-scoped; core.mdc references AGENTS.md), .cursor/skills/ |
| Cross-tool skills | .agents/skills/ (Agent Skills standard), plus ~/.agents/skills/ and ~/.cursor/skills/ on sync |
Edit prompt-guide.yml, run prompt-guide sync, and all enabled tools stay in sync.
prompt-guide.yml
│
▼ core/render (normalize → CanonicalRule[])
│
├── generic adapter → AGENTS.md (short index + shared context)
├── claude adapter → CLAUDE.md, .claude/*
├── codex adapter → .codex/instructions/*, config.toml
└── cursor adapter → .cursor/rules/*.mdc, skills
Design goals
- Single normalization layer — path rules, skills, and agents are parsed once; adapters only format and place files.
AGENTS.mdas canonical baseline — path-specific detail lives in overlays (.mdc,.codex/instructions/,.claude/rules/), not duplicated inAGENTS.md.- Per-rule
targets— apply a rule tocursoronly,codexonly, etc., instead of global tool on/off. - Manifest lockfile —
.prompt-guide/manifest.jsontracks file hashes so sync can skip hand-edited files and CI can fail on drift.
npm install -g @pelagornis/prompt-guide
cd your-project
prompt-guide init # interactive — creates prompt-guide.yml
prompt-guide sync # writes tool config files + manifest
prompt-guide doctor # verify setup and driftNon-interactive (CI / scaffolding):
prompt-guide init --yes --template web-react --name my-appOne-off without global install:
npx @pelagornis/prompt-guide init
npx @pelagornis/prompt-guide syncProject types: ios-swift, web-react, web-vue, python, node, custom.
| Command | Description |
|---|---|
init |
Create prompt-guide.yml (interactive or --yes) |
sync |
Generate or update tool config files and manifest |
diff |
Preview changes; distinguishes YAML drift vs manual edits |
validate |
Validate prompt-guide.yml |
doctor |
Diagnose config, missing files, and manifest drift |
status |
Per-adapter summary of file states |
add skill |
Add a skill entry to the config |
add rule |
Add a path rule |
add agent |
Add a Claude subagent |
| Option | Description |
|---|---|
--yes, -y |
Non-interactive mode (use with --template) |
--template <type> |
Project type: ios-swift, web-react, node, … |
--name <name> |
Project name (non-interactive) |
--git <source> |
Remote template: owner/repo/path@ref or a github.com/.../blob/... URL |
| Option | Description |
|---|---|
--dry-run |
List files without writing |
--force |
Overwrite files even if manually modified |
--ci |
Exit with code 1 if YAML or generated files drift from manifest |
--tool <name> |
claude, codex, cursor, or generic only |
Drift behavior: On sync, if a generated file was changed by hand and its hash no longer matches .prompt-guide/manifest.json, that file is skipped with a warning. Use --force to overwrite. In CI, use sync --ci to fail when drift is detected.
Single file at the project root:
version: "1"
project:
name: my-app
type: web-react
description: Short project summary
tools:
claude_code: true
codex: true
cursor: true
generic: false # true = AGENTS.md only (Gemini CLI, Windsurf, …)
context:
tech_stack: [React, TypeScript]
summary: |
Shared context for all tools. Keep concise — commands, principles, links.
path_rules:
- name: react-components
path: ["**/*.{tsx,jsx}"]
targets: [cursor, codex, claude] # omit = all enabled tools
content: |
- Functional components + hooks
skills: [] # → .agents/skills/ + tool copies
agents: [] # → .claude/agents/ (Claude only; use targets: [claude])
hooks: {}
forbidden: []
cursor:
always_apply_rules: [core]Optional fields: $schema, globs (alias for path on path rules), targets on path_rules / skills / agents.
See templates/<type>/prompt-guide.yml and example/prompt-guide.yml for full examples.
After sync, typical layout:
your-project/
├── prompt-guide.yml # source of truth (commit)
├── .prompt-guide/
│ └── manifest.json # drift lockfile (commit for CI)
├── AGENTS.md # shared baseline (generic adapter)
├── CLAUDE.md # @AGENTS.md + Claude index
├── .claude/
├── .codex/
├── .cursor/
└── .agents/skills/ # cross-tool Agent Skills
Gitignore generated tool output if you prefer — but commit prompt-guide.yml and .prompt-guide/manifest.json when using sync --ci. See example/.gitignore for a sandbox pattern.
The example/ directory is a gold-standard reference layout (layered AGENTS.md, targets, Codex-only rules, manifest CI).
pnpm build
pnpm example:sync
pnpm example:doctor
pnpm example:ci # drift check (exit 1 on mismatch)Details: example/README.md. Per-tool loading rules: docs/tool-compatibility.md.
pnpm install
pnpm build
pnpm pg sync # node packages/cli/dist/index.js
pnpm example:sync # test in example/
pnpm test| Script | Description |
|---|---|
pnpm pg |
Run CLI from packages/cli/dist |
pnpm example:* |
sync, doctor, validate, diff, status, ci in example/ |
Architecture and contributor notes: DEVELOP.md, docs/tool-compatibility.md, CONTRIBUTING.md.
MIT. See LICENSE.