Agent-Skills.md

Agent Skills: Vertesia Tool Server Resource

Creates tools, skills, interactions, content types, and rendering templates for the Vertesia plugin tool server. Handles file scaffolding and module resource index wiring. Use when adding new tool server resources to this plugin.

UncategorizedID: vertesia/composableai/vertesia-tool-server-resource

Repository

vertesia/composableai
vertesiaLicense: Apache-2.0
51

Install this agent skill to your local

pnpm dlx add-skill https://github.com/vertesia/composableai/tree/HEAD/templates/plugin-template/.agents/skills/vertesia-tool-server-resource

Skill Files

Browse the full folder contents for vertesia-tool-server-resource.

Download Skill

Loading file tree…

templates/plugin-template/.agents/skills/vertesia-tool-server-resource/SKILL.md

Skill Metadata

Name
vertesia-tool-server-resource
Description
Creates tools, skills, interactions, content types, and rendering templates for the Vertesia plugin tool server. Handles file scaffolding and module resource index wiring. Use when adding new tool server resources to this plugin.

Vertesia Tool Server Resource

Step-by-step guide for creating tool server resources. Each resource follows the same workflow:

  1. Create files in the appropriate src/modules/app/resources/<type>/<collection>/ directory
  2. Export from the collection's index.ts
  3. Register the collection in src/modules/app/resources/<type>/index.ts (only when adding a new collection)

For full code templates of every resource type, see REFERENCE.md.

Conventions

  • All imports use .js extensions: import { x } from "./foo.js"
  • Use satisfies for type validation ({} satisfies Tool<T>, {} satisfies InCodeTypeSpec, …)
  • Icons are SVG strings exported as default from .ts files
  • Import hooks (?skill, ?skills, ?prompt, ?template, ?templates, ?raw) only work in Rollup-compiled tool-server code, not in UI code
  • Snake_case for resource names (my_tool, my_type); PascalCase for TypeScript exports (MyTool, MyType)
  • User-owned resources live in src/modules/app/resources/<type>/
  • See src/modules/examples/resources/<type>/ for working starter code when the examples module is available

Resource types

Tool

Three files in src/modules/app/resources/tools/<collection>/<tool-name>/:

| File | Purpose | |------|---------| | schema.ts | TypeScript interface + JSONSchema (satisfies JSONSchema) | | <impl>.ts | The run function — uses ToolExecutionPayload<P>, returns ToolResultContent | | index.ts | Tool<P> definition (satisfies Tool<ParamsT>) |

Then export from src/modules/app/resources/tools/<collection>/index.ts as a ToolCollection.

→ Code in REFERENCE.md § Tool.

Skill

Files in src/modules/app/resources/skills/<collection>/<skill-name>/:

| File | Required | Purpose | |------|----------|---------| | SKILL.md | yes | YAML frontmatter + instructions for the agent | | properties.ts | no | Runtime gating (isEnabled) | | *.tsx | no | Widgets (compiled to dist/widgets/) | | *.py, *.js | no | Scripts (copied to dist/scripts/) |

Skills are auto-discovered: the collection imports ./all?skills — no per-skill imports needed.

→ Code in REFERENCE.md § Skill.

Interaction

Two flavors:

  • Template-based — prompt.hbs + prompt_schema.ts + result_schema.ts + index.ts (InteractionSpec importing the prompt via ?prompt).
  • Code-based — index.ts only, with prompts: [{ role, content, content_type }, …] inline. Use this for agents/conversations.

Then export from src/modules/app/resources/interactions/<collection>/index.ts as an InteractionCollection.

→ Code in REFERENCE.md § Interaction (template-based) and § Interaction (code-based).

Content Type

One file per type in src/modules/app/resources/types/<collection>/<type-name>.ts (InCodeTypeSpec), then a ContentTypesCollection in types/<collection>/index.ts.

Key fields: name (snake_case), object_schema (JSON Schema with additionalProperties: false), table_layout (columns for the UI), is_chunkable, strict_mode.

→ Code in REFERENCE.md § Content Type.

Rendering Template

Folder per template in src/modules/app/resources/templates/<collection>/<template-name>/:

  • TEMPLATE.md with YAML frontmatter (description, type: 'document' | 'presentation', optional title, tags)
  • Asset files (SVG, LaTeX, PNG) — auto-discovered, copied to dist/templates/

Templates are auto-discovered: the collection imports ./all?templates.

→ Code in REFERENCE.md § Rendering Template.

Collection registration

Once a collection is exported from src/modules/app/resources/<type>/<collection>/index.ts, add it to the array in src/modules/app/resources/<type>/index.ts:

// src/modules/app/resources/tools/index.ts
import { MyTools } from "./my-collection/index.js";

export const tools = [MyTools];

src/tool-server/app-server-modules.ts is generated from active modules and config.ts imports from it, so no further server wiring is needed.

Each collection needs an SVG icon.svg.ts (default string export). Code in REFERENCE.md § Collection registration & icons.

Verification

After creating a resource:

  1. pnpm build:server
  2. pnpm start
  3. Check the admin UI at http://localhost:3000/ — your resource should appear.
  4. Or hit the API: curl http://localhost:3000/api/tools (or /skills, /interactions, /types, /templates).