Agent Scripts: A Personal Skill Mirror for Codex and Claude, Built to Stay Idempotent

What Problem This Solves

Agent scripts solve a specific annoyance for developers who run multiple AI coding agents across several repositories: keeping shared instructions and skills in sync. The README describes this repo as the canonical place for AGENTS.MD, skills, scripts, and hooks. Without such a central store, each project would drift with its own copy of agent rules, and new machines would need manual setup. The target user is clearly Peter himself, but the design generalizes to anyone with a similar multi-repo, multi-agent workflow. The core pain is that Codex and Claude Code have different skill discovery mechanisms. Codex scans nested directories, while Claude Code only loads skills one level deep. This repo bridges that gap with a script that builds a per-machine mirror.

How sync-skills Builds the Mirror

The sync-skills script is the heart of the repo. It creates symlinks in two locations. For Codex, it makes whole-root links: ~/.codex/skills/agent-scripts points to ~/Projects/agent-scripts/skills. For Claude Code, it creates a flat mirror: each skill gets its own symlink under ~/.claude/skills/<name>/SKILL.md. The README notes that Claude Code follows per-entry symlinks but does not scan category subfolders, a behavior verified on version 2.1.197. The script also handles name collisions with a priority order: agent-scripts, then manager, then codex-local. It prints skipped duplicates and prunes broken or stale managed links. The script is idempotent, meaning running it repeatedly produces the same result without clobbering real files. This is a deliberate design choice: it prints changes only, so you can see what it did.

Getting It Running: Commands and Config

There is no install command in the README. You clone the repo into a fixed location, ~/Projects/agent-scripts, because the symlink targets assume that path. The primary command is scripts/sync-skills, which you run on every Mac after cloning or adding skills. For validation, you run scripts/validate-skills, which checks every skills/*/SKILL.md for YAML front matter with required name and description fields. You can enable it as a local git hook with git config core.hooksPath hooks. There is also scripts/docs-list.ts, a TypeScript helper that walks docs/ and enforces summary and read_when front matter. For browser automation, scripts/browser-tools.ts offers commands like start --profile, nav <url>, eval '<js>', screenshot, and console. You can compile it to a binary with bun build scripts/browser-tools.ts --compile --target bun --outfile bin/browser-tools. The repo also links global AGENTS.MD files: ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md, and ~/.claude/AGENTS.md all point to the shared AGENTS.MD.

Skills as the Routing Layer

Skills are the main routing layer, according to the README. Each skill lives in skills/<name>/SKILL.md with YAML front matter containing a name and a short generic description. The description is optimized for routing, not documentation. Skill bodies should be terse and operational. When a workflow has repeatable commands, the README advises putting helper scripts under skills/<name>/scripts/. The repo exposes skills from other places via symlinks. For example, skills/autoreview points to ../../agent-skills/skills/autoreview, and skills/discrawl points to ../../discrawl/.agents/skills/discrawl. This lets repo-owned skills stay canonical in their own repos while being exposed here. The current list includes birdclaw, discrawl, gog, imsg, slacrawl, wacli, and wacrawl. This is a clever way to avoid duplication, but it ties the repo to a specific directory structure outside the repo itself.

A Real Limitation: Fixed Paths and Single-User Assumptions

The most obvious limitation is the hardcoded path ~/Projects/agent-scripts. The README uses this path in every symlink example. If your projects live elsewhere, you must edit the script or change your directory layout. The script is also designed for a single machine and a single user. It creates symlinks in home directories, which works for Peter's personal workspaces but not for a team sharing a repo. The README says to run sync-skills on every Mac after cloning, which assumes each developer has the same relative project layout. Another limitation is the Claude Code version dependency. The flat-skill scanning behavior was verified on 2.1.197, but newer versions might change how symlinks are resolved. The script prunes broken links, which is good, but it cannot protect against future behavioral changes in the agents themselves.

The Wrong Tool for Some Cases

This repo is the wrong tool if you need cross-platform support. The scripts are shell-based and the paths use Unix-style home directories. Windows would require significant changes. It is also wrong for teams that need to share skills across many developers without a common project root. The sync mechanism relies on symlinks, which can cause issues on filesystems that do not support them well, such as some network drives or container mounts. If you prefer a package manager to distribute agent skills, this repo does not offer that. You would instead write your own installer or use a tool like dotfiles managers. The README explicitly says to keep scripts dependency-free and portable, but that portability is within the Unix world, not beyond it.

Alternatives: Different Approaches to Agent Skill Management

A common alternative is to vendor agent instructions directly into each repository. Many projects include their own AGENTS.md or CLAUDE.md files with full content, not pointers. That approach avoids symlinks and external dependencies, but it creates duplication and drift. Another alternative is to use a dedicated dotfiles or configuration management tool like chezmoi or GNU Stow to manage symlinks. Those tools handle symlink creation generically, but they do not understand agent-specific quirks like Claude Code's flat-skill requirement. A third alternative is to use a plugin system built into the agent, such as Claude Code's built-in skill discovery, if it ever supports nested directories. The key difference is that agent-scripts centralizes the logic for handling multiple agents with different rules, while alternatives either duplicate content or require you to write that logic yourself.

Maintenance and License Implications

The repo is actively maintained, with the latest release 0.12.0 pushed on 2026-07-17. The README describes a sync workflow for downstream repos: pull latest here first, ensure each target repo starts with a pointer-style AGENTS.MD, preserve repo-local rules below the pointer, and copy helper changes both directions only when the helper is meant to stay byte-identical. This is a manual process, not automated by a script. The maintenance cost is real: you must keep the shared repo updated and then manually sync downstream repos. The license is MIT, which permits commercial use, modification, and redistribution with attribution. The README does not mention any contributor guidelines or issue templates, so external contributions are not clearly structured. This is a personal repo, and its maintenance depends on one person's workflow.

Editorial conclusion

Adopt agent-scripts if you are a solo developer or small team running Codex and Claude Code on macOS, want a single canonical source for agent rules, and accept a symlink-based mirror that assumes a fixed project layout. Do not adopt it if you need cross-platform support, multi-user collaboration, or a package manager distribution. Before adopting, verify that your Claude Code version matches the documented flat-skill scanning behavior (2.1.197) and that your downstream repos can tolerate pointer-style AGENTS.MD files. Check the MIT license terms for your use case, and test sync-skills on a dry run to see which links it would prune.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes