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.