VaultysClaw agent-controller.instructions.md

Agent Controller Conventions

Module Imports

No @/* alias — use relative paths for local imports:

import { shellTool } from "./tools/shell";
import { getDb } from "../db";

Cross-package: import { AgentCapability, WSMessage } from "@vaultysclaw/shared" — never relative paths across package boundaries.

Adding a Tool

Create src/tools/<name>.ts, export a single AgentToolDefinition constant:

import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import type { AgentToolDefinition } from "./types";

export const myTool: AgentToolDefinition = {
  name: "my-tool",
  capability: "internet_access", // see AgentCapability below
  requiresApproval: false, // true for system-modifying operations
  tool: createTool({
    id: "my-tool",
    description: "...",
    inputSchema: z.object({ url: z.string() }),
    execute: async ({ url }) => {
      /* ... */
    },
  }),
};

Then register in src/tools/index.ts by adding to the builtIn array inside createToolRegistry().

requiresApproval: true for anything that writes files, runs shell commands, or executes code.

AgentCapability values: file_access | internet_access | browser_control | api_call | mail_send | code_execution | system_command | agent_communication | knowledge_search

Adding a Skill

Skills are runtime-loaded plugins — they must ship as compiled .js/.mjs, not .ts.

Structure a local skill under skills/<name>/index.ts, compiled to skills/<name>/index.js:

import type { SkillDefinition } from "../../src/skills/types";

export const skill: SkillDefinition = {
  name: "my-skill",
  description: "...",
  version: "1.0.0",
  tools: [
    /* AgentToolDefinition[] */
  ],
  systemPromptExtension: "Optional: guidance for the LLM about these tools.",
};

Accepted export forms: export const skill = ... or export default { skill: ... }.

The loader scans SKILLS_DIR for .js/.mjs files and index.js/index.mjs inside subdirectories. New skills require a restart (or trigger SkillLoader.load()) unless SKILLS_WATCH=true.