Agent Scripts — Shared Agent Instructions & Skills
Shared agent rules, reusable skills, and lightweight helpers for Codex and Claude Code.
Evidence shows scripts and skills, but no permission model or user confirmation mechanism. Scripts like browser-tools.ts may execute arbitrary JS, but permission boundaries are not stated. Dependencies declare commander and puppeteer-core, but no security audit or locked versions. External effects like filesystem modifications and network access are not clearly stated. Rollback mechanism not mentioned. Source attribution: README and LICENSE clearly attribute to Peter Steinberger, but publisher is unverified.
Self-consistency: README describes scripts and skills, CI config aligns, but no full tests. Dependency availability: dependencies declared, but no locked versions or integrity checks. Failure messages: scripts like validate-skills may output errors, but no detailed error handling docs.
Audience and scenarios: README clearly targets personal workspace, but no other user scenarios. Capability boundaries: skills and scripts functionality described, but no explicit limits. Trigger precision: skill descriptions are short, but no trigger examples. Environment fit: scripts designed cross-platform, but no Windows support notes.
Information architecture: README structured, but no directory index. Install notes: global setup and sync methods provided, but no detailed install steps. Naming stability: consistent naming, but no version stability notes. Examples and FAQ: command examples provided, but no FAQ. Known limitations: not mentioned. License: MIT clear. Versioning and changelog: not provided. Maintenance responsibility: README mentions sync and update, but no explicit maintainer.
Output usability: scripts like browser-tools provide command help, but no output format specs. Marginal value: provides reusable skills and scripts, but limited value. Cost-benefit: few dependencies, but no performance or resource assessment.
Claim traceability: README claims align with files, but no verification methods. Cross-source corroboration: CI and README corroborate, but no external verification. Fact-inference separation: README distinguishes facts and inferences, but not explicitly.
- Publisher identity unverified, treat with caution.
- Scripts may execute arbitrary code, review permissions.
- Dependencies not pinned, supply chain risk.
- No user confirmation mechanism, may auto-execute actions.
What does this agent do, and when should you use it?
Agent Scripts is the canonical repository for shared agent instructions, skills, and portable helper scripts used in Peter's local workspaces. It contains AGENTS.MD for hard rules, skills/ for workflow skills with YAML front matter, scripts/ for dependency-light helpers, and hooks/ for local guardrails. The core mechanics revolve around scripts/sync-skills, which builds a per-machine skill mirror for Codex and Claude Code and maintains symlinks to the shared AGENTS.MD. Additionally, scripts/validate-skills checks skill metadata, and browser-tools.ts offers a standalone Chrome DevTools helper. This repository is ideal for developers seeking a consistent way to configure local coding agents.
The repository provides a shared AGENTS.MD with hard rules, installed via symlinks to ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md, and ~/.claude/AGENTS.md. The scripts/sync-skills script creates whole-root skill links for Codex (e.g., ~/.codex/skills/agent-scripts -> ~/Projects/agent-scripts/skills) and flat per-skill links for Claude Code (~/.claude/skills/<name>/SKILL.md), resolving name collisions and pruning broken links. scripts/validate-skills checks every skills/*/SKILL.md for required YAML front matter (name and description) and can be enabled as a git hook via git config core.hooksPath hooks. scripts/docs-list.ts enforces summary and read_when front matter in docs/. scripts/browser-tools.ts provides commands like start --profile, nav <url>, eval '<js>', and screenshot for Chrome DevTools automation.
- Developers using Codex or Claude Code who want consistent agent rules across repositories, using pointer-style AGENTS.MD.
- Synchronizing skills and instructions across multiple machines by running scripts/sync-skills.
- Teams that want to validate skill definitions automatically via git hooks with validate-skills.
- Developers needing browser automation for testing or scraping, using browser-tools.ts.
- Maintainers of multi-repo projects who need to ensure submodules reference shared agent instructions.
- Skill authors who want to create reusable skills following the SKILL.md structure and register them via sync-skills.
What are this agent's strengths and limitations?
- Clear routing via SKILL.md YAML front matter with short generic descriptions optimized for agent matching.
- Idempotent sync script that never clobbers real files and prunes stale symlinks safely.
- Standalone browser-tools.ts enables Chrome DevTools automation without heavy dependencies.
- Validation tools (validate-skills, docs-list.ts) enforce metadata quality across skills and docs.
- Designed for macOS; Windows/Linux users may need manual adjustments.
- Coupled to specific Codex and Claude Code behaviors, which may change with updates (e.g., Claude Code 2.1.197).
- Relies on absolute paths like ~/Projects/agent-scripts; relocation requires reconfiguration.
- Tailored to Peter's personal workflow; generic use may require customization.
How do you install or deploy this agent?
Clone the repository: git clone https://github.com/steipete/agent-scriptsPrerequisites: macOS (scripts designed for Mac), git, optional Bun for compiling browser-tools.ts.
Initialize: run scripts/sync-skills to create global symlinks.
Set up git hooks: git config core.hooksPath hooksHow do you use this agent?
Ensure your project references the shared instructions: insert READ ~/Projects/agent-scripts/AGENTS.MD BEFORE ANYTHING (skip if missing) in your AGENTS.MD. Add new skills under skills/ with proper SKILL.md front matter, then run validate-skills to check. Run sync-skills to synchronize skills and instructions. For browser-tools.ts, optionally build a binary with bun build scripts/browser-tools.ts --compile --target bun --outfile bin/browser-tools, then use commands like start --profile, nav <url>.