Skip to content
Skills Library
Management & product · Building & coding

new-tool

/new-tool

Builds a company tool in the hub (a screen and its tools for the AI), with its permission, its table and its tests. Use it when someone asks for a new screen, list, form or automation inside the hub.

Licence
MIT
Last repository change
10.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: example/app/(hub)/issues/actions.ts, example/app/(hub)/issues/page.tsx, example/tests/issues.test.mjs, example/tools/issues.ts

What it does and when to use it

Builds a company tool in the hub (a screen and its tools for the AI), with its permission, its table and its tests. Use it when someone asks for a new screen, list, form or automation inside the hub.

Original author description

Builds a company tool in the hub (a screen and its tools for the AI), with its permission, its table and its tests. Use it when someone asks for a new screen, list, form or automation inside the hub.

How it works

  1. Before writing code
  2. The parts
  3. How to write an AI tool
  4. The screen
  5. Using a connector from a tool
  6. Using a device from a tool
  7. Check
  8. What not to do
Original SKILL.md headings · 87 lines, 848 words
SKILL.md preview
---
name: new-tool
description: Builds a company tool in the hub (a screen and its tools for the AI), with its permission, its table and its tests. Use it when someone asks for a new screen, list, form or automation inside the hub.
---

# New tool

A hub tool is one job of the company solved in one place: a screen for people and, with the same logic, MCP tools for their AIs. Both go through the same permission and leave the same trace in the log.

The `example/` folder of this skill holds a complete, tested tool, "Issues". Copy it as a starting point: the five files sit at the same paths they would have in the project.

## Before writing code

1. Ask who will use it, what that person does by hand today, and what they want to see when they open the screen. A tool solves one job. If two jobs come up, they are two tools.
2. Search the log (`log_search`) for anything already decided about that job.
3. Check whether the data already lives in a service that has a connector. If it does, the tool reads it with `callConnector()` and does not copy it into a table of its own.
4. Say in three lines what you are going to build and wait for approval.

## The parts

Choose a short lowercase slug, for example `orders`. Everything hangs from it.

1. Permission: `tool:orders`. If reading and changing are done by different people, two permissions: `tool:orders` and `tool:orders:manage`.
2. Table, if needed: a new file in `db/migrations/` with the next number. End it with `enable row level security` and the `revoke` from the example. Apply it with `npm run migrate`.
3. Logic and AI tools: `tools/orders.ts`. The database functions are exported so the screen can use them. Below them, the array of tools defined with `defineTool({...})`.
4. Registering the tools: in `tools/index.ts`, import the array and add it to `COMPANY_TOOLS`.
5. Screen: `app/(hub)/orders/page.tsx` and `actions.ts`. The page and every action start with `await requireAccess(PERMISSION)`.
6. Menu: an entry in `menu` in `hub.config.ts` with `href`, `title`, `icon` and `permission`. If a new icon is needed, add it to `components/icon.tsx`.
7. Test: `tests/orders.test.mjs`, like the one in the example. It checks the logic and that a person without the permission does not see the tool.

## How to write an AI tool

The AI decides from the name and the description. Write them for someone who does not know the company.

- `name`: `thing_verb`, in lowercase: `orders_search`, `order_create`.
- `description`: what it does, when to use it and what not to do. If it writes or deletes, tell the AI to confirm with the person first.
- `input`: a `z.object` with `.describe()` on every field, with an example inside the text.
- Output: just enough to decide the next step. No personal data that is not needed.
- `readOnly: true` if it changes nothing. `skipLog: true` only for reads that are repeated very often.
- `area`: one of the areas in `hub.config.ts`, so the log can be filtered.
- If the permission depends on the arguments, use `permissionFor`. See `connector_request` in `lib/mcp/core.ts`.

Errors are thrown with `throw new Error("a sentence a person can understand")`. The AI receives that text.

## The screen

Follow `docs/DESIGN.md`. The minimum:

- `<PageHeader>` with one sentence that says what the screen is for, in the company's own words.
- One column, in the order of the work. No tabs.
- Forms with server actions, which go back to the page with `?ok=` or `?error=`, shown with `<Notice>`.
- An empty state that says what the first step is.
- Anything that changes shared data is written to the log with `writeLog()`.

## Using a connector from a tool

```ts
import { callConnector } from "../lib/connectors.ts";

const r = await callConnector("shop", { path: "/orders", query: { status: "pending" } });
if (r.status !== 200) throw new Error(`The shop responds ${r.status}`);
const orders = JSON.parse(r.body);
```

A company tool that calls a connector asks for its own permission (`tool:orders`), and the connector's permission is not needed. That way a role can see the pending orders without free access to the whole API of the shop.

## Using a device from a tool

```ts
import { enqueueJob } from "../lib/devices.ts";

await enqueueJob("warehouse-printer", "print", { text: "Order 102" }, person.name);
```

The events that devices send (a card read, an alarm) are in the `device_events` table.

## Check

1. `npm run check` with no errors.
2. `npm run demo`: sign in with a role that has the permission and with another that does not. The second must not see the menu entry, and typing the address by hand sends them back to Home.
3. Look at the screen at 390 px wide and in dark mode.
4. Call each tool over MCP and check the line it leaves in the log.
5. Grant the permission to the right roles in Team → Roles. Update `docs/STATUS.md` and add the change to the log.

## What not to do

- A page or an action without `requireAccess()`.
- SQL with a person's text pasted inside it. Always use parameters.
- Storing a service key in a table of the tool. Connectors exist for that.
- Touching `lib/` or the core screens to solve something for a single tool.
Files in this package (6)
  • SKILL.md 5 KB
  • example/app/(hub)/issues/actions.ts 2 KB
  • example/app/(hub)/issues/page.tsx 3 KB
  • example/db/migrations/0002_issues.sql 1 KB
  • example/tests/issues.test.mjs 2 KB
  • example/tools/issues.ts 3 KB

Versions

The database has no other skills named new-tool.

Database snapshot: 13.11.2026 · package version 76b3dd05aaa5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100new-hub
    Turns the template into the hub of one specific company. Interviews the person who commissions it, sets the name, color, areas and roles, prepares the database, creates the first person and proposes the first connectors and tools. Use it when starting a new hub or when someone…
  • 90agent-tool
    Add or modify a tool of the Order Hub retention AI agent (lib/agent), or change its prompt/model settings. Use when the user wants the agent to answer a new kind of question or access new data.
  • 100dx-hub-status
    Show hub dispatch status — which repos are running, done, blocked or failed. Use for 'hub status', 'what's running'.
  • 100new-screen
    Generate a new screen (list, detail, create/edit form, report, or settings page) in an HTMX + PHP + Bootstrap 5.3 application built with this plugin. Use when the user asks to "add a screen", "create the customers page", "build the edit form", or invokes /new-screen. Guarantees…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.