Tool Creator

Links such as references/... are files of this skill. Read them with read_tool_file. In the terminal agent, read_item with tool-creator gives the folder; then call read_file on the folder plus the link.

Understand the need

• Find out what the tool should do: its input, its output, and who uses it (the model in a chat, the terminal agent, or an App). Ask one short question when the answer changes the design.
• Check that no tool does this already: find_tools in a chat, cluaiz skill list, cluaiz plugin list or cluaiz mcp list, or the family.json files in cluaiz-tools. Extend an existing tool rather than making a second one.
• When the tool goes into a repository, read that repository's AGENTS.md and CONTRIBUTING.md.

Choose the type

A WebAssembly plugin cannot read files or start programs. Use MCP for that.

Create

• Call create_tool. Pass the category, a tool_id, a name, a description and triggers. An MCP tool also needs command and args, with the package version pinned. The tool is written to the Engine's tools folder. When the open folder is cluaiz-tools, it is also added there and to family.json. An existing tool is replaced only with overwrite: true and the user's yes.
• Description:
  • Written in the third person.
  • Says what the tool does and when to use it, in the words a user would say.
  • Broad enough to cover neighbouring tasks.
  • The model chooses tools from the description, so it is the most important line.
• Functions:
  • A verb-first name.
  • A one-sentence description.
  • Each parameter has a type and a short description.
  • Keep them short: in a small context, the schemas of all installed tools share about 8,000 characters.
• Next steps: do only what next lists, and add no files the user did not ask for.
• Plugins:
  • Write the logic in src/lib.rs and build with cargo build --release --target wasm32-unknown-unknown.
  • Copy the file in as <tool_id>.wasm, and update functions when the inputs change.
  • The Engine passes only the arguments, not the function name, so a plugin with several functions tells them apart by their arguments.

Check and test

1. Validate. Call validate_tool with tool_id or path. Fix every error, read the warnings, and call it again. What it cannot see: references/validation-rubric.md.
2. Run the code directly.
   • A script: with a small JSON file of arguments.
   • A plugin: with cargo test.
   • An MCP server: start it and check that it lists its tools.
3. Run it through a model. Use good input and bad input. Bad input must give a clear error, not a crash.
4. Test a skill as an evaluation.
   • Pick two or three real tasks, and run them with and without the skill.
   • Use a small model and a large model.
   • Fix what the small model gets wrong.
   • Cut whatever the large model did not need.
5. Report. Say what you tested and what you did not. Do not say it works before it has run.

Publish

Tools are shared through the cluaiz-tools repository, which takes pull requests. When the user wants a tool published, and it validates and passes its tests, commit it and open a pull request with the git-assistant and github skills.

Rules

• Declare every dependency with need (required, recommended, optional) and info, and every permission the tool uses with info and allow (network also with access); the user reads both at install and can refuse permissions: references/skill-authoring.md.
• Never put keys or passwords in a tool's files. Every tool type names the keys and settings it reads in env.
• SKILL.md is for the model: short judgement rules and limits, with no diagrams or long examples. README.md is for people: it explains what the tool does and includes a Mermaid diagram with quoted labels.
• Links are relative to the tool folder, and every file is listed in versions.<version>.files.
• The family key, the folder name and the id stay the same.