# steipete/agent-scripts: shared agent rules and a skill mirror for Codex and Claude > A small MIT-licensed repository that keeps one set of agent instructions and skills canonical, then builds a per-machine mirror so Codex and Claude Code both find them. The interesting part is the sync script, not the skills themselves. **steipete/agent-scripts** — Scripts for agents, shared between my repositories. scripts/sync-skills Builds the per-machine skill mirror: Codex whole-root links, Claude flat per-skill links, shared AGENTS.MD pointers. - Repository: https://github.com/steipete/agent-scripts - Website: https://steipete.me - Stars: 6,651 · Forks: 545 - Language: Shell - License: MIT - Published: 2026-08-04 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/steipete-agent-scripts ## The problem: the same agent rules copied into every repository Agent instruction files drift. A rule gets added in one repository, another keeps the old wording, and a third has a local edit nobody remembers making. steipete/agent-scripts treats one repository as canonical for those rules and for reusable skills, and everything else points at it. The README states this directly: the repo is "the canonical place for" AGENTS.MD, skills/, scripts/ and hooks/. Downstream repositories are supposed to hold a pointer line instead of a copy, with repo-specific rules below it. That is the whole idea. It is aimed at one person's local workspaces (the README says "Peter's local workspaces"), so treat it as a pattern to imitate rather than a product to install. The scripts are dependency-light by design, and the README asks that helpers stay byte-identical when copied in both directions. ## How scripts/sync-skills builds the per-machine mirror The two agents do not discover skills the same way, and that asymmetry is the reason the script exists. Codex scans nested directories, so it gets whole-root links: ~/.codex/skills/agent-scripts points at the repository's skills folder, and ~/.codex/skills/manager points at another repo's skills folder. Claude Code is stricter. According to the README, it loads only ~/.claude/skills//SKILL.md, exactly one level deep, follows per-entry symlinks but does not scan category subfolders, a behaviour the README says was verified on 2.1.197. So Claude gets a flat mirror with one link per skill, covering both repositories plus machine-local extras under ~/.codex/skills/. Collisions resolve in a fixed order: agent-scripts, then manager, then codex-local. The script prints skipped duplicates and prunes broken or stale links it manages. It is described as idempotent and as never clobbering real files, which matters because a wrong write into ~/.claude/skills could overwrite a hand-written skill. Skills themselves are folders under skills/, each with a SKILL.md carrying YAML front matter with name and description. The README's rule for descriptions is short and generic, optimized for routing rather than documentation, and it asks that description be quoted. Some skills are not stored here at all: public shared skills live in ../agent-skills, and repo-owned skills stay canonical in their own repositories, exposed through tracked relative symlinks such as skills/autoreview -> ../../agent-skills/skills/autoreview. The README names birdclaw, discrawl, gog, imsg, slacrawl, wacli and wacrawl as current symlinked repo-owned skills. ## Installing agent-scripts and running the first sync There is no package to install. The README's instruction is to clone the repository on every Mac, then run the sync script; it says to run it "on every Mac after cloning or adding skills". The README gives these two commands. The sync script prints changes only, so a clean second run should print nothing: ```bash git clone https://github.com/steipete/agent-scripts scripts/sync-skills ``` After that, ~/.codex/skills/agent-scripts and ~/.claude/skills/ entries should exist for each skill. The README lists the shared instruction-file links as tilde paths with arrow notation, and notes that Claude Code reads CLAUDE.md only, which is why it points at the shared AGENTS.MD: ```text ~/.codex/AGENTS.md -> ~/Projects/agent-scripts/AGENTS.MD ~/.claude/CLAUDE.md -> ~/Projects/agent-scripts/AGENTS.MD ~/.claude/AGENTS.md -> ~/Projects/agent-scripts/AGENTS.MD ``` In a downstream repository, the README gives the pointer form as one line, with repo-specific rules below it: ```text READ ~/Projects/agent-scripts/AGENTS.MD BEFORE ANYTHING (skip if missing). ``` Before editing any skill, enable the validation hook and run the validator. The README gives the hook as a git config command, and the validator checks every skills/*/SKILL.md for YAML front matter plus the required name and description fields: ```bash git config core.hooksPath hooks scripts/validate-skills ``` Two optional helpers round this out. scripts/docs-list.ts walks docs/ and enforces summary and read_when front matter. scripts/browser-tools.ts is a standalone Chrome DevTools helper; the README's common commands are start --profile, nav , eval '', screenshot, console, network, search --content "", content , inspect and kill --all --force. The README also gives this build line for an optional binary: ```bash bun build scripts/browser-tools.ts --compile --target bun --outfile bin/browser-tools ``` ## Where the design bites: collisions, platform assumptions and silent failures The collision order is a real constraint, not a footnote. If two repositories both define a skill called review, the agent-scripts copy wins and the other is skipped. The script prints the duplicate, but printing is not the same as failing, so a shadowed skill can sit unused for a while before anyone notices. The platform assumption is harder to work around. Every path in the README is a macOS home directory path, the sync is described as something to run "on every Mac", and the mechanism is symlinks plus git config core.hooksPath. On Windows this needs a different approach, and the README does not describe one. The Claude side is also version-sensitive: the one-level-deep rule is stated as verified on 2.1.197, which means a future Claude Code release could change discovery and leave the flat mirror pointing at nothing useful. The README does not document rollback, so undoing a sync means removing links by hand. Finally, this is a personal canonical repository. The README refers to "Peter's local workspaces", so a fork inherits the naming and the collision order of someone else's setup. None of that makes the approach wrong; it makes it a pattern you adapt rather than a tool you adopt unchanged. ## Alternatives: a skill manager, or plain dotfiles The closest alternative is not another repository but a different mechanism: a package manager or dotfile manager that installs skills into each agent's directory from a manifest. The difference is in who owns the state. A manager records what it installed and can uninstall it; scripts/sync-skills instead inspects the target directories, creates links it recognises as its own, prunes broken or stale managed links, and leaves everything else alone. That is more forgiving when you edit skills by hand, and less predictable when you want to know exactly what is on disk. The second alternative is doing nothing structured: keep AGENTS.MD in each repository and copy the shared blocks. That works until the blocks diverge, which is the failure this repository exists to prevent. A third option is to let each agent keep its own native skill layout and skip the mirror entirely. That removes the collision order and the version sensitivity, but it also removes the single source of truth, so a skill added under Codex would not appear under Claude without manual work. ## Maintenance, licence and what upgrading costs The last push to main was on 2026-07-17, and the most recent release is 0.12.0 on the same date. The repository is not archived. That is roughly two months before the date of writing, so the project is not stale, but the README does not describe a support policy, a compatibility matrix or a deprecation process, and a personal canonical repo can go quiet without anyone announcing it. Upgrade cost is low by construction. The only declared dependencies are commander ^15.0.0 and puppeteer-core ^25.9.0 in package.json, and those are used by the TypeScript helpers, not by the sync script. The README's rule that scripts stay dependency-free and portable, with no repo-specific imports or path aliases, is what keeps that true. The practical upgrade risk is not a version bump; it is a change in how Codex or Claude Code discovers skills, which would require editing the sync logic rather than pulling a new release. The licence is MIT, which permits reuse and modification with the licence and copyright notice preserved; the LICENSE file at the repository root carries the terms. That is a description of the licence, not legal advice. ## Conclusion Adopt it if you run Codex or Claude Code on a Mac and are tired of copying the same instruction blocks into every repository; the pointer-style AGENTS.MD and scripts/sync-skills are the two pieces worth taking. Do not adopt it if you work on Linux or Windows, or if you want a packaged tool rather than a canonical repo you clone and wire by hand. Before committing, check what scripts/sync-skills would link on your machine, confirm your Claude Code version treats ~/.claude/skills one level deep the way the README describes, and decide whether you accept that name collisions resolve agent-scripts first. ## FAQ ### How do I install steipete/agent-scripts? There is no package to install. The README says to clone the repository on every Mac and run scripts/sync-skills, which builds the Codex whole-root links, the Claude flat per-skill links and the shared AGENTS.MD pointers. ### What does scripts/sync-skills actually change on my machine? It creates ~/.codex/skills/agent-scripts and ~/.codex/skills/manager as whole-root links, a flat set of ~/.claude/skills/ links covering both repositories plus machine-local ~/.codex/skills/ extras, and the shared instruction-file links. The README describes it as idempotent, printing changes only, pruning broken or stale managed links and never clobbering real files. ### Why does Claude Code get a flat per-skill mirror instead of whole-root links? According to the README, Claude Code loads only ~/.claude/skills//SKILL.md, exactly one level deep, and follows per-entry symlinks but does not scan category subfolders, verified on 2.1.197. Codex scans nested directories, so it can take whole-root links. ### How do I validate a skill before committing it? Enable the local hook with git config core.hooksPath hooks, then run scripts/validate-skills. The README says it checks every skills/*/SKILL.md for YAML front matter plus the required name and description fields. ## Sources - [Official documentation](https://steipete.me) - [Official README](https://github.com/steipete/agent-scripts#readme) - [Project repository](https://github.com/steipete/agent-scripts) - [Release notes](https://github.com/steipete/agent-scripts/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/steipete-agent-scripts