tool-handler-development
Skill9 starsChanged 6 months agoMITView on GitHub
Create or modify Bazel MCP tool handlers. Use when adding new tools, editing tool definitions, creating handler modules, or working with files under src/tools/handlers/.
In this repository7 other files it gives its agents.
- cli-developmentSkill
- device-and-uiSkill
- example-projectSkill
- mcp-setupSkill
- simulator-workflowSkill
- swift-agent-debug-logSkill
- swift-agent-debug-logSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 0 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Every handler file under src/tools/handlers/ must export:
- Very specific: line 28
Add the tool definition to definitions.
- Very specific: line 29
Add the case to handle().
- Very specific: line 30
If it's a new handler file, register it in src/tools/bazel-tools.ts (import + add to the aggregated arrays).
- Very specific: line 31
Update the expected tool count in handlers/handlers.test.ts.
- Very specific: line 32
If the tool uses Bazel commands, include startupArgs in the schema.
- Very specific: line 58
Use asStringArray(args.configs, 'configs') for array params — don't double-wrap with configArgs().
- Very specific: line 59
Use resolveSimulatorFromArgs(args) for simulator resolution (returns { sim, warning }).
- Very specific: line 60
Use prependWarning(message, warning) to attach resolution warnings to output.
- Very specific: line 67
Add the new tool name to bazel-tools.test.ts expected set.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Tool Handler Development
Handler Contract
Every handler file under src/tools/handlers/ must export:
export const definitions: ToolDefinition[] = [...]
export function canHandle(name: string): boolean { ... }
export function handle(name: string, args: Record<string, unknown>): Promise<ToolResult | undefined>canHandlereturnstruefor tool names this handler owns.handlereturnsundefinedfor unknown tools (not an error).definitionsis an array of tool definitions withname,description,inputSchema, and optionalstartupArgs,streaming,requiredfields.
Adding a New Tool
- Pick the right handler file based on domain (build, simulator, device, etc.) or create a new one.
- Add the tool definition to
definitions. - Add the case to
handle(). - If it's a new handler file, register it in
src/tools/bazel-tools.ts(import + add to the aggregated arrays). - Update the expected tool count in
handlers/handlers.test.ts. - If the tool uses Bazel commands, include
startupArgsin the schema.
Tool Definition Schema
{
name: 'bazel_ios_<action>',
description: 'One-line description of what the tool does',
inputSchema: {
type: 'object',
properties: { ... },
required: ['target'],
},
startupArgs: true, // if tool accepts --startup_arg flags
streaming: true, // if tool supports streaming output
}Workflow Categories
Tools belong to one of 19 workflows: build, test, simulator, app_lifecycle, capture, ui_automation, deep_links, device, lldb, macos, tvos, watchos, visionos, spm, project, scaffold, session, daemon, update.
Assign the workflow in the handler or the workflow mapping. bazel_list_workflows and bazel_toggle_workflow are always included regardless of filtering.
Common Patterns
- Use
asStringArray(args.configs, 'configs')for array params — don't double-wrap withconfigArgs(). - Use
resolveSimulatorFromArgs(args)for simulator resolution (returns{ sim, warning }). - Use
prependWarning(message, warning)to attach resolution warnings to output. - Wrap
readBundleIdcalls in try/catch — they can throw after a successful build+install. - Escape quotes in
--predicatestrings:.replace(/"/g, '\\"')on interpolated values.
Testing
- Tool name ordering in tests must use
.sort()— import order across modules is not guaranteed. - Add the new tool name to
bazel-tools.test.tsexpected set. - Many handlers shell out to external tools — E2E testing against
example_projects/BazelAppis the primary validation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

