agent-scripts README

The project's README from github.com/steipete/agent-scripts. As one markdown file: README.md.

Agent Scripts

Shared agent instructions, skills, and small portable helpers for Peter's local workspaces.

This repo is the canonical place for:

Skills

Skills are the main routing layer. Each skills/<name>/SKILL.md has YAML front matter:

---
name: skill-name
description: "Short generic trigger phrase."
---

Rules:

Global discovery is built by scripts/sync-skills (idempotent; run on every Mac after cloning or adding skills):

For the specific legacy topology ~/.claude/skills/NAME/NAME -> ~/.codex/skills/NAME -> ~/.claude/skills/NAME, invoke the sync owner directly with an explicit allowlist:

/absolute/path/to/agent-scripts/scripts/sync-skills --repair-nested-self-links --dry-run -- boxd-cli boxd-setup-deploy

/absolute/path/to/agent-scripts/scripts/sync-skills --repair-nested-self-links -- boxd-cli boxd-setup-deploy

This mode validates every candidate before unlinking only the extra nested leaves. It preserves the real skill directories, assets, and valid Codex backlinks, and exits before creating roots, building mirrors, pruning, or touching instruction pointers. Names must start with an ASCII letter or digit and contain only letters, digits, ., _, or -; duplicates, missing names, and unknown arguments are rejected. A missing nested leaf is a no-op only with the expected surrounding topology. Redirected/inaccessible roots, unexpected objects or literal targets, and changed directory/link identities cause refusal. Rechecks before each unlink are not atomic concurrency protection; a later error stops the batch and reports removals already completed, without rollback.

The read-only skills/fleet-maintenance/scripts/agent-skill-links-audit.sh reports same-name nested ancestor loops as reason=nested-self-link. This is narrow detection, not an exhaustive graph validator. Its --repair remains a broad sync through ~/Projects/agent-scripts/scripts/sync-skills; it is not the scoped repair above. Run scripts/test-sync-skills for isolated fixture coverage; scripts/test-sync-skills --recurrence-only /absolute/path/to/old-sync-skills runs the unchanged recurrence assertion against an original helper.

Shared personal skills live as real folders in skills/. Public OpenClaw shared skills live in ../agent-skills and are exposed here with tracked relative symlinks. Repo-owned skills stay canonical in their repo and are exposed here the same way, for example:

skills/autoreview -> ../../agent-skills/skills/autoreview
skills/discrawl -> ../../discrawl/.agents/skills/discrawl

Current symlinked repo-owned skills include birdclaw, discrawl, gog, imsg, slacrawl, wacli, and wacrawl.

Agent Instructions

Shared hard rules live in AGENTS.MD.

Global setup (also maintained by scripts/sync-skills; Claude Code reads CLAUDE.md only, so it links to the shared AGENTS.MD):

Downstream repos should use a pointer-style AGENTS.MD:

READ ~/Projects/agent-scripts/AGENTS.MD BEFORE ANYTHING (skip if missing).

Repo-specific rules go below that pointer. Do not copy the shared blocks into downstream repos.

Helpers

scripts/sync-skills

scripts/validate-skills

scripts/docs-list.ts

scripts/browser-tools.ts

Syncing

Treat this repo as canonical for shared agent rules and portable helper scripts.

When syncing downstream repos:

For submodules, repeat the pointer check inside each subrepo, push those changes, then bump submodule SHAs in the parent repo.

agent-scripts (steipete/agent-scripts)

Searching Database…

7.4K ·GitHub
Agent-scripts
What is this?A personal toolbox for AI coding agents: shared agent instructions, reusable workflow skills and small portable scripts kept in one canonical repo and synced into the author's Codex and Claude Code setups.
So is this a tool I install, or a repo I clone and wire into my own agents?Not an app — it is a repo you clone and wire in. scripts/sync-skills builds per-machine symlinks so both agents discover the skills and shared AGENTS.MD from this canonical copy.
How do I set it up on my machine?Clone it and run scripts/sync-skills on every Mac after cloning or adding skills. It links skills into each agent's skills directory and points both agents at the shared AGENTS.MD; it is idempotent and prints only changes.
Which coding agents does it actually work with?Codex and Claude Code. Codex scans nested dirs, so it gets whole-root links; Claude Code reads only one level of ~/.claude/skills, so sync builds it a flat per-skill mirror instead.
What happens if I already have my own skills or files that collide with its names?Sync never clobbers real files and reports conflicts instead. Name collisions resolve agent-scripts > manager > codex-local, and the author warns the unlink rechecks are not atomic concurrency protection.
It has thousands of stars — is it meant for other people too, or is it just the author's personal setup?It is primarily Peter's own setup for his repositories, but the pieces are portable: pointer-style AGENTS.MD, per-agent skill mirrors and validation hooks are designed to be copied into any workspace.
What is a skill here, exactly?A folder with a SKILL.md that has YAML front matter with a required name and a short routing description. Skills live in skills/ (some repo-owned ones are exposed via tracked symlinks), and scripts/validate-skills checks every one.
Can the skill checks run automatically?Yes. Enable the bundled git hook with git config core.hooksPath hooks, and scripts/validate-skills will verify valid YAML front matter plus the required name and description on every SKILL.md.
What does the browser-tools helper do?scripts/browser-tools.ts is a standalone Chrome DevTools helper: start with a profile, nav, eval JS, screenshot, read console and network, inspect elements, kill instances. It can also be compiled into a single binary with bun build.
How do downstream repos stay in sync with these rules?They keep a pointer-style AGENTS.MD that links back to this repo, put repo-specific rules below the pointer, and never copy shared blocks in. Helper changes are copied between repos only when they must stay byte-identical.
What are similar projects?Claude-Code-Game-Studios, superpowers-zh, ralph, claude-code-infrastructure-showcase, plannotator, marketingskills, leanrea, oh-my-openagent
Which topics is it in?scripting, dotfiles, hooks, yaml, bun, claude-skills, git, shell, skills, claude, agent-skills, codex
Creator
steipete
Size
2.4 MB
Stars
7.4K
Updated
CommitOct 18Release0.12.0Jul 17
Age
11mo
Commits · 90 Days