AI-Tools
Global Claude Code and Codex skills/agents, versioned in one place so they stay in sync across devices.
Contents
- Skills & agents
- Product dualities
- Install
- Structure
- How it works
- Add artifacts
- Project-local maintenance skills
- Development
- CI checks
Skills & agents
Reusable slash-command skills and custom agents for Claude Code and Codex — covering everything from committing, PR creation, and CI diagnosis to CLAUDE.md audits and cross-tool sync. One clone, available everywhere.
| Target | Skills | Agents |
|---|
| Claude Code | 19 | 1 |
| Codex | 19 | 1 |
Full catalogs: Claude Code · Codex
Product dualities
Some global skills are intentionally product-specific pairs. The skill name names the
destination product, and each product only carries the direction it can write:
| Claude Code skill | Codex skill | Direction |
|---|
agents-to-claude-md | claude-md-to-agents-md | Instruction docs between AGENTS.md and CLAUDE.md |
audit-claude-md | audit-agent-docs | Product-specific instruction doc audits |
where-claude | where-agents-md | Product-specific instruction doc placement |
port-project-claude | port-project-codex | Project-local skills and agents into the destination product |
sync-claude-permissions | sync-codex-permissions | Project-local permissions into the destination product |
These pairs are intentional parity exceptions. Add new destination-specific pairs to
scripts/check-parity.sh and mention them here when they are introduced.
Install
git clone https://github.com/ada-ggf25/AI-Tools.git ~/AI-Tools
cd ~/AI-Tools
./install.sh # both Claude Code and Codex (default)
./install.sh --claude # Claude Code only
./install.sh --codex # Codex only
Restart Claude Code or start a new Codex session after installing.
Set CODEX_HOME to override the Codex home directory (default: ~/.codex).
To sync on another device later: git pull && ./install.sh.
Structure
global/claude/skills/ ← Claude Code skills, one directory per skill [global]
global/claude/agents/ ← Claude Code custom agents (.md) [global]
global/codex/skills/ ← Codex skills, one directory per skill [global]
global/codex/agents/ ← Codex custom agents (.toml) [global]
install.sh ← symlinks this repo into Claude Code and/or Codex
.claude/ ← PROJECT-LOCAL Claude Code config (settings, hooks, project skills)
.codex/ ← PROJECT-LOCAL Codex config (rules, config.toml)
.agents/ ← PROJECT-LOCAL Codex skills (only active inside this repo)
global/claude/ and global/codex/ are the global artifact source — symlinked into
~/.claude/ and ~/.codex/ and available in every project. The dot-prefix dirs
(.claude/, .codex/, .agents/) are the project-local config layer — only active
when Claude Code or Codex is opened inside this repository.
How it works
install.sh creates symlinks from the global tool home into this repo so edits here are live in the next session — no copy step needed.
- Claude Code:
~/.claude/skills/<name> → global/claude/skills/<name>/ and ~/.claude/agents/<name>.md → global/claude/agents/<name>.md
- Codex:
${CODEX_HOME:-~/.codex}/skills/<name> → global/codex/skills/<name>/ and ${CODEX_HOME:-~/.codex}/agents/<name>.toml → global/codex/agents/<name>.toml
install.sh is idempotent: already-correct symlinks are skipped; pre-existing non-symlink entries are skipped with a warning.
Add artifacts
Claude Code skill: create global/claude/skills/<name>/SKILL.md, run ./install.sh, restart Claude Code.
Use /new-skill to scaffold the file correctly.
Claude Code agent: create global/claude/agents/<name>.md, run ./install.sh, restart Claude Code.
Codex skill: create global/codex/skills/<name>/SKILL.md, run ./install.sh --codex.
Codex agent: create global/codex/agents/<name>.toml, run ./install.sh --codex.
See CLAUDE.md for full authoring conventions and metadata requirements.
Project-local maintenance skills
Two skills live in the project-local config directories and are only available when
working inside this repo. They are the primary tools for keeping Claude and Codex
global artifact sets in sync.
These follow the same destination-product duality as the global paired skills: the
Claude Code-side maintenance skill writes into global/claude/, while the Codex-side
maintenance skill writes into global/codex/. Each treats the opposite product tree as
the read-only source for that run.
| Skill | Location | Trigger | What it does |
|---|
codex-to-claude | .claude/skills/codex-to-claude/ | "sync from codex", "port codex skill to claude" | Finds Codex skills/agents with no Claude counterpart, adapts them to Claude Code format, and writes them to global/claude/ after per-item approval |
claude-to-codex | .agents/skills/claude-to-codex/ | "sync from claude", "port claude skill to codex" | Finds Claude skills/agents with no Codex counterpart, adapts them to Codex format, and writes them to global/codex/ after per-item approval |
These skills are project-scoped on purpose — they reference repo-internal paths and
parity rules (e.g., the audit-claude-md ↔ audit-agent-docs equivalence) that would
be meaningless in any other repository.
Development
Three things run automatically — don't duplicate them manually:
- PostToolUse hook (
scripts/on-skill-change.sh) — fires after Write/Edit to any managed skill/agent file; re-runs the relevant install target and regenerates the artifact catalogs in global/claude/README.md and global/codex/README.md.
- Pre-commit hook (
scripts/validate-skill.sh) — errors if staged managed artifacts are missing required metadata, invalid TOML, or description: lacks trigger phrases.
- CI — validates all managed artifacts, checks catalog files are in sync, checks Claude/Codex parity, runs shellcheck, Python syntax checks, ruff, and markdownlint.
Commits follow Conventional Commits: feat(skills):, fix(install):, chore:, etc.
CI checks
The GitHub Actions workflow runs on every push and pull request:
| Job | What it checks | Local equivalent |
|---|
validate-artifacts | Every managed Claude and Codex skill/agent: names match folders, required metadata exists, trigger phrases present, Codex TOML parses. | scripts/validate-skill.sh --all |
catalogs-in-sync | Regenerates global/claude/README.md, global/codex/README.md, and the counts in README.md from frontmatter, then fails if any were not committed after a skill/agent change. | python3 scripts/sync-readme.py && git diff --exit-code README.md global/claude/README.md global/codex/README.md |
parity-check | Verifies that every skill and agent exists in both Claude Code and Codex, with an explicit allowlist for known intentional asymmetries (audit-claude-md↔audit-agent-docs, where-claude↔where-agents-md, agents-to-claude-md↔claude-md-to-agents-md, port-project-claude↔port-project-codex, sync-claude-permissions↔sync-codex-permissions). | scripts/check-parity.sh |
lint-bash | ShellCheck over install.sh and all scripts in scripts/. | shellcheck install.sh scripts/*.sh |
python-syntax | Byte-compiles scripts/sync-readme.py to catch syntax errors. | python3 -m py_compile scripts/sync-readme.py |
python-lint | Ruff against Python scripts for style and static issues. | ruff check scripts/ |
lint-markdown | markdownlint-cli2 against every .md file; rules configured in .markdownlint.json. Any finding fails the job. | markdownlint-cli2 "**/*.md" "#node_modules" |
Before opening a PR, run the checks available locally. CI installs Ruff and markdownlint-cli2 itself.
