agent-starter

agent-starter

A toolkit of skills, templates, and guides for bootstrapping AI-agent-friendly projects.

It started as Anthropic's own engineering patterns - extracted from the Claude Code CLI source and packaged into reusable form. It has since been extended with additional best practices, tooling, and original ideas that go beyond the source material. The flagship extension is a per-project self-improvement loop: scaffolded projects capture signal from their own usage and turn it into better rules over time (see below).

So the patterns here come from two places: those marked "derived from Anthropic's Claude Code source" are reverse-engineered from the real thing; everything else is added on top.

Usage

Point an AI agent at this repo and say "read this repo and set up my project" - the agent reads AGENT.md and scaffolds a complete project interactively:

read this repo and set up my project https://github.com/sneg55/agent-starter/

Or install the /new-project skill once and run it in any session:

npx skills add sneg55/agent-starter -a claude-code -g

Then: /new-project

For an existing project, say "read this repo and apply it to my project" - the agent reads ADOPT.md and runs an audit-first, opt-in adoption (nothing overwritten, everything on a branch). Or install the skills the same way and run /adopt-project.

For a whole team - making everyone get the same setup from a git pull (vendored hooks, shared config, plugin defaults) - see TEAM.md. It's the companion to ADOPT.md: where ADOPT.md installs into one developer's ~/.claude, TEAM.md ships the setup with the repo.

To install just the hooks (with their settings.json wiring merged idempotently via jq):

git clone https://github.com/sneg55/agent-starter && cd agent-starter
./install.sh   # add --with-read-guard for the read-before-edit pair

Or install every skill at once as a Claude Code plugin - this repo doubles as a plugin marketplace:

/plugin marketplace add sneg55/agent-starter
/plugin install agent-starter@agent-starter

That loads all the skills (/new-project, /adopt-project, /commit, /simplify, /reflect, /remember, /dream). Hooks are still wired via install.sh above.

Guides

guides/large-codebase-best-practices.md

Comprehensive best practices for setting up and scaling a large codebase with Claude Code - directory structure, file size targets, naming conventions, error handling, CLAUDE.md hierarchy, and more. All derived from analyzing Anthropic's own Claude Code CLI source.

guides/lint-rules-for-ai.md

Tiered Biome + ESLint ruleset tuned for AI-agent-driven TypeScript codebases. Blocks the specific mistakes LLMs make (dropped awaits, any escape hatches, hallucinated imports, half-finished functions) rather than enforcing arbitrary line caps. Biome handles fast syntactic rules + formatting; ESLint keeps type-aware and plugin-specific rules. Pairs with templates/biome.json, templates/eslint.config.mjs, and hooks/lint-on-edit.sh. Includes the Python half: the same tiers via ruff + pyright, pairing with templates/ruff.toml + templates/pyrightconfig.json.

guides/hooks-reference.md

Complete reference for Claude Code's hook system - all 4 hook types, all 27 events, exit code behavior, configuration format, and 10 practical examples (auto-lint, block dangerous commands, agent verification, security review, Slack notifications, and more).

guides/tool-authoring-pattern.md

The BashTool/-style directory-per-tool layout extracted from Claude Code's own source. Each tool is a handful of single-purpose files (toolName.ts, schema.ts, prompt.ts, validation.ts, permissions.ts, security.ts, execute.ts, result.ts). Gives an agent a predictable place to look when editing any tool and breaks whole classes of import cycles.

guides/error-id-registry.md

Every thrown error carries a stable ID (E_CFG_003) from a central registry. Logs, telemetry, docs, and agents all reference the same ID, so error-message rewordings don't break grep or alerting. Pairs with templates/errorIds.ts (TS) and templates/error_ids.py (Python).

guides/discriminated-union-results.md

Result<Ok, Err> as the one shape every fallible function returns. Exhaustiveness-checked via the compiler; no ad-hoc {success, data} / {ok: 1} drift across edits. Reserves throws for programmer errors only.

guides/abort-signal-threading.md

Thread AbortSignal through every long-running call so Ctrl+C, timeouts, and obsoleted work actually stop. Covers the canonical entry-point shape, AbortSignal.any for composed timeouts, the AbortError swallow anti-pattern, and an ESLint rule idea for bare fetch().