Agents Toolkit

Reusable skills, hooks, scripts, and workflow accelerators for coding and non-coding agents.

Contents

• skills/ contains task-specific agent instructions and supporting code.
• hooks/ contains lifecycle hooks that can be adapted to an agent runtime.
• mods/ contains Claude Code UI mods and companions for usage, cache timing, check evidence, batch progress, and design choices. See mods/README.md for the global setup and update workflow.
• scripts/ contains small utilities for agent status, workflow visibility, and validating skill folders against the spec.
• agent-config/ contains the canonical shared skills/MCP synchronization manifest for Claude Code, Claude Desktop, and Codex.
• desktop/local-context/ documents the scoped, read-only context bridge and personal desktop plugin setup. Its server is in mcps/local-context/.

Run scripts/agent-sync.py audit to inspect drift. Sync a single category with scripts/agent-sync.py sync --only skills, --only mcps, or --only hooks.

Syncing agents

The repository is the source of truth for shared skills and MCPs:

./scripts/agent-sync.py audit  # read-only drift check
./scripts/agent-sync.py sync --only skills  # link skills only
./scripts/agent-sync.py sync --only mcps    # merge MCP entries only
./scripts/agent-sync.py sync --only hooks   # apply hook adapters only

The sync command updates Claude Code, Claude Desktop, and Codex without copying credentials. OAuth/API authentication remains local to each client. Conflicting global skill folders are moved to ~/.agent-sync-backups/ before they are replaced with links to this repository.

Before uploading changes to GitHub, run:

./scripts/agent-sync.py audit
python3 -m py_compile scripts/agent-sync.py
jq empty agent-config/mcps.json
git diff --check
git status --short

Review the final diff and confirm that reports, logs, credentials, local settings, and backup directories are not included. Then commit and push from the repository owner account.

Skills

Original

• caffeinate for unattended overnight runs, with power, disk, deadline, and process-tree guardrails.
• foundry-client for calling an OpenAI-compatible LLM proxy with retries, strict-JSON mode, and usage logging.
• new-demo for scaffolding a FastAPI and vanilla-JS LLM demo project.
• transcript-to-todo for turning a meeting transcript into a structured todo list that separates decisions from suggestions.
• brand-ui-prototyping for iterating from approved brand assets and page content through homepage hero options, feedback, and themed HTML prototypes.
• requirement-reconciliation for comparing updated scope, reference designs, and stakeholder feedback with the current build and verification evidence.
• local-context-search for source-linked retrieval from explicitly selected local note folders, with stale-source detection and a private SQLite index.

Adapted from upstream workflows

• decision-lens for difficult decisions, reviews, diagnosis, and strategy.
• agent-cli-design for reliable tools, scripts, scaffolds, and hooks.
• investigative-analysis for evidence-backed data investigation.
• decision-visualization for honest charts, dashboards, tables, and maps.
• playwright-verification for console, network, accessibility, and responsive checks against a live page, with a bundled Playwright script that exits non-zero so a run can be gated.
• document-pipeline for PDF and document extraction, generation, and review.
• delivery-review for concise post-task learning after complex work.
• interactive-explanation for simulations, scrollytelling, and explorable stories.

These skills were inspired by the agent workflows in sanand0/scripts, then rewritten and adapted for this toolkit's preferences, workflows, and portability requirements. They are not vendored copies of the upstream skills.

Upstream concept	This toolkit
expert-lens	decision-lens
agent-friendly-cli	agent-cli-design
data-analysis	investigative-analysis
data-viz	decision-visualization
devtools	playwright-verification
pdf	document-pipeline
post-mortem	delivery-review
interactive-storytelling	interactive-explanation

Adapted from starred repositories

• isometric-illustrations for detailed SVG objects, cutaways, and physical mechanism explainers, adapted from Anatomy. Includes its MIT drawing kit, optional WebGL layer, and a small example; complements architecture diagrams and interactive explanation workflows.
• architecture-diagrams for source-backed system maps and standalone interactive diagrams, adapted from Archify.
• security-audit for coverage-led vulnerability reviews with verified findings, adapted from Cloudflare's security audit skill.
• skill-learning for distilling and consolidating lessons from agent work, adapted from AutoHarness. This is a portable, manually invoked workflow; AutoHarness's plugin and automatic hooks are not installed.

Local usage and skill evaluation

Count explicit skill invocations and literal read requests across accessible Claude and Codex session logs, without exporting prompts or session identifiers:

uv run scripts/audit_agent_activity.py --skills-only
uv run scripts/audit_agent_activity.py --skills-only --since 2026-10-01T00:00:00Z

This mode prints aggregate JSON and coverage gaps, writes no reports, and does not inspect project settings. A request to read a skill does not establish that the read succeeded, or that the skill helped. Unsupported commands and log formats can be missed; undated records are excluded with --since.

For earlier project decisions, use local-context-search with explicitly selected note roots. The index stays outside Git and makes no network requests. For comparing instruction changes, use skill-learning and its bundled references/task-evaluation.md: fixed tasks, baseline/candidate snapshots, observable acceptance checks, and held-out examples. No paid evaluation runs or external uploads happen automatically.

These are original adaptations of ideas from sanand0/scripts and promptevals, not copied source files.

Run the local utility regression checks with:

uv run --no-project python -m unittest discover -s scripts/tests

Automatic knowledge for coding agents

local-context-search gives Claude Code and Codex automatic project knowledge from an approved, project-scoped history index, without a maintained notes folder or repeated skill invocation. Session preflight guides agents to retrieve a bounded briefing when earlier context matters, followed by focused evidence reads. The backend uses incremental local parsing, ranked full-text search, duplicate passage suppression, bounded reads, and source-linked reviewed memories with explicit supersession. There are no model calls or automatic approval inference. Private databases and trial state remain outside Git. See history memory and desktop setup.

The optional Obsidian review vault is generated by scripts/obsidian_memory.py. It links projects, reviewed memories, candidates and bounded evidence, protects manual edits, and can refresh hourly through a local user LaunchAgent. Obsidian is not required by agent retrieval. Private vault contents stay outside Git.

Validating skills

scripts/validate_skills.py checks skill folders against the Agent Skills spec: frontmatter, name and description shape, body length, layout, unreferenced bundled files, and a signal-density heuristic that flags a skill made only of advice a capable model already follows.

uv run scripts/validate_skills.py skills                 # findings
uv run scripts/validate_skills.py skills --score         # ranked against the guidance
uv run scripts/validate_skills.py skills --score --detail # per-criterion breakdown
uv run scripts/validate_skills.py skills --output json   # machine-readable

The scoring criteria come from the spec and Anthropic's authoring guidance; the weights are a judgement call, so treat the numbers as relative rankings rather than absolute grades. Exit codes: 0 clean, 1 findings at or above --fail-on, 2 usage error.

Principles

• Keep secrets in environment variables, never in source or configuration files.
• Treat transcripts, session state, logs, caches, and local settings as private.
• Adapt paths and provider-specific settings before installing these tools.
• Review generated output before using it in client-facing or high-stakes work.

License

MIT. See LICENSE.