Utilities: Prompts & Resources — Weavetab Docs — Weavetab Docs

Utilities: Prompts & Resources — Weavetab Docs

Authoring / slash prompts and @ dynamic context resources in Weavetab plugins. Official technical documentation for Utilities: Prompts & Resources on lo...

# Utilities: Prompts & Resources

In the Model Context Protocol, **Prompts** and **Resources** represent zero-tool-call interactions between users, AI clients, and servers.

On `weavetab.dev/discover`, these capabilities are indexed together under the **Utilities** tab:
- **Prompts (`/`)**: Pre-packaged prompt templates and shortcuts that appear in chat client `/` command menus.
- **Resources (`@`)**: Dynamic data endpoints that agents and users attach as context using `@` mentions.

---

## 1. Authoring `/` Prompts (`definePrompt`)

Prompts allow your plugin to supply specialized instructions, workflows, or audit checklists to the AI agent:

```typescript
import { definePrompt, z } from "@weavetab/sdk";

export const reviewPrPrompt = definePrompt({
  name: "review_pr",
  description: "Analyzes pull request diff for security vulnerabilities and breaking changes",
  arguments: {
    prNumber: z.number().int().describe("Pull request number"),
    strictness: z.enum(["advisory", "blocking"]).default("advisory").describe("Review severity"),
  },
  handler: async ({ prNumber, strictness }, { tab }) => {
    // handler runs on the server when the user invokes /review_pr in their AI client
    const activeUrl = (await tab?.url()) || "detached";

    return `You are conducting a ${strictness} security review on Pull Request #${prNumber}.
Active Tab Context: ${activeUrl}

Checklist:
1. Identify all changed API contracts and exported types.
2. Flag any un-sanitized user inputs or SQL/CDP injection vectors.
3. Verify that all newly added dependencies are declared in package.json.
4. If strictness is "blocking", fail the review if test coverage is omitted.`;
  },
});
```

### Prompt Registration Rules
1. **Permission Required**: Declaring or registering prompts requires `permissions.prompts: { add: true, reason: "..." }` in `weavetab.json`.
2. **Reserved Names**: Core prompts (`/page_context`, `/agent`) cannot be overridden. Attempts to register them will throw an error.
3. **Session Access**: The second argument `{ tab }` provides access to the active browser tab (if one exists).

---

## 2. Authoring `@` Resources (`defineResource`)

Resources provide agents with read-only access to live data, logs, or diagnostic payloads without requiring the agent to call an execution tool.

### Static URI Resources

Use a fixed URI for singleton data feeds:

```typescript
import { defineResource } from "@weavetab/sdk";

export const rateLimitResource = defineResource({
  name: "github-ratelimit",
  uri: "github://ratelimit",
  description: "Live GitHub API quota, remaining requests, and reset timestamp",
  mimeType: "application/json",
  read: async (uri, _vars, { tab }) => {
    const quota = await checkQuota();
    return JSON.stringify(quota, null, 2);
  },
});
```

### Dynamic URI Templates (RFC 6570)

Use URI templates with `{variable}` parameters when resources represent indexed entities:

```typescript
export const prDiffResource = defineResource({
  name: "github-pr-diff",
  uriTemplate: "github://pr/{id}/diff",
  description: "Git diff for a specific pull request number",
  mimeType: "text/x-diff",
  // Populate autocomplete in client @ mention pickers
  list: async () => {
    const openPrs = await fetchOpenPrs();
    return openPrs.map(pr => ({
      uri: `github://pr/${pr.number}/diff`,
      name: `PR #${pr.number}: ${pr.title}`,
    }));
  },
  // Dynamic autocomplete callback when user types in client
  complete: {
    id: async (prefix) => {
      const numbers = await searchPrNumbers(prefix);
      return numbers.map(String);
    },
  },
  // Resource reader handler
  read: async (uri, vars, { tab }) => {
    const prId = vars.id;
    const diff = await fetchPrDiff(prId);
    return diff;
  },
});
```

---

## 3. Registering Utilities in Plugins

```typescript
import { definePlugin, type PluginContext } from "@weavetab/sdk";
import { reviewPrPrompt } from "./prompts/review.js";
import { rateLimitResource, prDiffResource } from "./resources/github.js";

export default definePlugin({
  name: "@weavetab/plugin-github",
  version: "1.0.0",
  instructions: "GitHub PR inspection utilities and rate limit resources.",

  // Static registration
  prompts: [reviewPrPrompt],
  resources: [rateLimitResource, prDiffResource],

  async onLoad(ctx: PluginContext) {
    ctx.logger.info("GitHub utilities registered.");
  },
});
```

---

## 4. Automatic Secret Redaction

All data returned by `read()` handlers in resources and prompt outputs generated by `handler()` pass through Weavetab's `SessionSecretTracker` before reaching the MCP client.

Any credentials, bearer tokens, or sensitive patterns stored in Weavetab's secrets vault (`~/.weavetab/secrets.json`) are automatically scrubbed and replaced with `[REDACTED_SECRET]`.