@askverb/skill

MIT. Teach your coding agent to define what a Verb assistant may do in your product.

npx @askverb/skill install

Then ask your agent:

add Verb to this app

It reads your codebase and writes a verb.md listing the actions your users' assistant will be allowed to perform, classified, described, and checked.

Why this exists

The hard part of setting up an in-product assistant is not pasting a script tag. It is writing good tool definitions. The descriptions in them load into the model's context and steer its calling behaviour, so they are the difference between an assistant that picks the right action and one that picks a plausible one.

You cannot reasonably be expected to know that. But your coding agent already knows your codebase, which is the one thing Verb never will. So rather than asking you to describe your API to us, this teaches your agent to do it.

Local first, network optional

The skill writes a file on your disk. It does not call our API, needs no key, and works offline. You read the verb.md before anything reaches Verb.

That ordering is deliberate. The file decides what an AI may do inside your product, so it should arrive as a diff a second person can read, not as a row somebody edited in a dashboard at midnight.

What is in it

verb/
├── SKILL.md                  the entry point, kept short
├── references/
│   ├── format.md             the complete verb.md specification
│   ├── descriptions.md       how to write a description that works
│   ├── stacks.md             where to look, per framework
│   └── safety.md             classification, and the BaaS problem
└── scripts/
    ├── validate.mjs          check a verb.md, offline
    ├── scaffold.mjs          write a starter verb.md
    └── lib/                  a copy of the server's own rules

Skills load progressively: your agent reads the description and pulls the full instructions only when a task matches, so leaving it installed costs almost nothing.

The validator

node verb/scripts/validate.mjs verb.md
node verb/scripts/validate.mjs verb.md --json

lib/ is a byte-for-byte copy of @askverb/authoring, which the Verb server also runs. A file that passes here is a file that imports. Exit code 0 means clean or warnings only, 1 means errors or safety blocks, 2 means the file could not be read.

It refuses some things outright, and the refusals are the interesting part:

• a destructive Supabase or Firebase tool that touches the table directly rather than going through a database function
• a filter appended inside an if, one missing argument from an unfiltered write
• a table or collection name taken from the model's arguments
• a write tool with no required arguments
• a cancel_* tool classified as read-only, which would skip the confirmation gate entirely

Each refusal comes with the fix, and there is no override, because the server applies the same rules.

Other agents

npx @askverb/skill install --dir .claude/skills   # somewhere specific
npx @askverb/skill install --global               # every project
npx @askverb/skill --print                        # the whole skill to stdout

Development

pnpm --filter @askverb/skill sync    # re-copy the rules from packages/authoring
pnpm --filter @askverb/skill test    # checks sync, then runs the suite

Never edit verb/scripts/lib/ by hand. Change packages/authoring/src and sync.