tool-synthesis

Creates and registers per-worktree scratch tools with automatic cleanup for agent use.

1|Updated Mar 15, 2026
One-click install
npx skills add https://github.com/paulingham/.claude --skill tool-synthesis-paulingham
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: tool-synthesis
Source: https://github.com/paulingham/.claude/tree/main/skills/tool-synthesis
Command: npx skills add https://github.com/paulingham/.claude --skill tool-synthesis-paulingham

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Enables developers to create per-worktree scratch tools to extend the agent's capabilities without contaminating the main codebase.

Core Features & Use Cases

  • Allows an engineer to author a tiny executable inside the worktree, register it, and call it from subsequent Bash invocations.
  • Stores scratch tools under ${WORKTREE}/.claude-scratch-tools with per-worktree isolation and a per-worktree registry.json for auditability.
  • Supports automatic gitignore protection and cleanup before merge to prevent leakage into main branches.

Quick Start

Register a scratch tool to extend the worktree functionality and run it from the per-worktree scratch-tools path.

Frequently Asked Questions about tool-synthesis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create temporary bash scripts in a git worktree without contaminating the main codebase?

You can create per-worktree scratch tools by authoring a small executable inside the worktree, registering it in a per-worktree registry, and calling it from Bash. A cleanup gate ensures the scratch tools are removed before merge to prevent main branch contamination.

What is per-worktree isolation for scratch tools and how does it work?

Per-worktree isolation stores scratch tools under a dedicated worktree path with a per-worktree registry.json for auditability, ensuring tools remain scoped to a single worktree and do not leak into the main codebase.

Can I run automated repo-specific searches and quick analyses without leaving persistent scripts behind?

Yes, per-worktree scratch tools support automated pipelines for repo-specific tasks such as fast searches and quick analyses. They are stored under an isolated worktree path and a cleanup gate ensures they disappear after use.

Does gitignore protection prevent scratch tools from leaking into the main branch during a merge?

Automatic gitignore protection and a mandated cleanup gate prevent scratch tools from leaking into main branches. Per-worktree isolation ensures the tools are scoped to a single worktree and removed before merge.

What's the best way to manage one-off bash executables for isolated development tasks?

The best way to manage one-off bash executables is using per-worktree scratch tools with a registry.json for auditability and executable permissions. This approach provides isolation and a cleanup gate to ensure tools disappear after use.