Creates and improves Bun-based tools for skills — decides when a tool earns its place, scaffolds zero-dependency scripts with dual output, validates tool quality, and wires tools into SKILL.md decision trees. Use when adding a tool to a skill, improving an existing tool, deciding whether something should be a tool or inline instructions, reviewing tool quality, or when the user says "add a tool to this skill", "write a validator for this skill", "make this repeatable", or "check this tool".
التثبيت
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Creates and improves Bun-based tools for skills — decides when a tool earns its place, scaffolds zero-dependency scripts with dual output, validates tool quality, and wires tools into SKILL.md decision trees. Use when adding a tool to a skill, improving an existing tool, deciding whether something should be a tool or inline instructions, reviewing tool quality, or when the user says "add a tool to this skill", "write a validator for this skill", "make this repeatable", or "check this tool".
allowed-tools
Read Grep Glob Bash Write Edit
Tool Creation
Decision tree
What are you doing?
Deciding whether to create a tool -> read references/when-to-create-tools.md, apply the earning criteria
Creating a new tool for a skill -> follow "Creating a tool" below
Improving an existing tool -> what's wrong?
Output is hard to parse programmatically -> add --json output mode per references/tool-conventions.md
Tool is a thin wrapper around a single command -> it probably shouldn't be a tool. Inline the command in SKILL.md and delete the tool file
Tool lacks help text or error handling -> fix per references/tool-conventions.md
Tool has external dependencies -> rewrite using only bun built-ins and node stdlib
Wiring a tool into a skill -> follow "Wiring into SKILL.md" below
Reviewing tool quality -> check against references/tool-conventions.md "Quality checklist"
Creating a tool
1. Validate the need
Before writing any code, confirm the tool passes at least one bar from references/when-to-create-tools.md. If it doesn't, put the command inline in SKILL.md instead.
2. Write the tool
Create scripts/<tool-name>.ts following the conventions in references/tool-conventions.md. Agent Skills, Codex, and Claude Code all treat scripts/ as the portable executable-code directory. If you are improving an existing repo skill that already has tools/, keep that path stable unless the task is explicitly to migrate it.
Key principles:
Zero external dependencies. Bun built-ins and node stdlib only.
Dual output: human-readable by default, --json for programmatic consumption.
Fail loudly: errors to stderr, non-zero exit codes, never silently swallow failures.
Self-documenting: --help describes what the tool does, its arguments, and its options.
3. Validate
After writing:
Run the tool with --help to verify the help text is clear
Run against a real target to verify it produces correct output
Run with --json to verify structured output is valid JSON
Run with missing/bad arguments to verify it fails cleanly
Wiring into SKILL.md
Add the tool to the appropriate decision tree branch — point to it from the action where it's useful
Reference it in the key references table at the bottom of SKILL.md
Don't duplicate the tool's logic in SKILL.md — just say when to run it and what to do with the output
Key references
File
What it covers
references/when-to-create-tools.md
Decision criteria for whether something should be a tool vs inline instructions
references/tool-conventions.md
Structural patterns, conventions, and quality checklist for building tools
