Registry Management

Registry Management

Overview

The personality-assistant-registry provides MCP server definitions and templates for the desktop app.

Primary files:

• registry.json (source of truth)
• templates/ JSON files (human-editable copies; keep in sync)
• docs/ markdown referenced by docs.path

Registry Structure

{
  "version": "X.Y.Z",
  "updatedAt": "ISO timestamp",
  "entries": [ /* MCP server definitions */ ],
  "templates": [ /* Prompts, skills, bundles, presets */ ]
}

Adding MCP Server Entries

Add to the entries array:

{
  "id": "my-mcp",
  "name": "My MCP Server",
  "summary": "Short description",
  "version": "1.0.0",
  "homepage": "https://github.com/...",
  "category": "workspace|communication|developer-tools|analytics|etc",
  "docs": {
    "path": "docs/my-mcp.md"
  },
  "runtime": {
    "preferred": "native|node",
    "fallback": "native|node"
  },
  "install": {
    "method": "manual|command",
    "instructions": "For manual installs...",
    "command": "npx -y @scope/mcp-server",
    "notes": "Required env vars..."
  },
  "artifacts": [
    {
      "platform": "windows|macos|linux",
      "arch": "x86_64|aarch64",
      "url": "https://github.com/.../releases/download/vX.Y.Z/file.zip",
      "sha256": "hash...",
      "filename": "file.zip",
      "entrypoint": "dist/index.js",
      "size": 12345
    }
  ],
  "env": [
    {
      "key": "API_TOKEN",
      "type": "secret|string|boolean|enum",
      "required": true,
      "label": "API Token",
      "help": "Description...",
      "placeholder": "...",
      "default": "...",
      "values": ["option1", "option2"],
      "advanced": false,
      "picker": "file|directory",
      "multiline": false
    }
  ]
}

Notes:

• install.method: "command" should be non-interactive (npx -y ...), especially for mcp-remote.
• docs.path must be a repo-relative file committed to the registry repo (no local absolute paths).
• requires values must reference entries[].id and must not include mcp: prefixes.

Adding Templates

Templates go in the templates array. Template types:

• assistant-prompt - Agent templates shown in Discover -> Agent Templates
• assistant-preset - Model presets shown in Discover -> Models & presets
• heartbeat-task - Background task prompts
• skill - Reusable skill definitions shown in Discover -> Skills
• skill-bundle - Skill pack metadata (Superpowers-style)
• plugin - Plugin definitions

Agent Templates (assistant-prompt)

{
  "id": "my-template",
  "type": "assistant-prompt",
  "name": "My Template",
  "summary": "Short description",
  "tags": ["tag1", "tag2"],
  "requires": ["some-mcp-id"],
  "prompt": "System prompt for this assistant...",
  "suggestions": ["A useful starter prompt", "Another suggested question"]
}

Heartbeat Tasks

{
  "id": "my-heartbeat",
  "type": "heartbeat-task",
  "name": "My Task",
  "summary": "Short description",
  "tags": ["tag1"],
  "requires": ["slack-mcp"],
  "task": {
    "prompt": "HEARTBEAT TASK: ...\n\n1. Step one\n2. Step two",
    "intervalMinutes": 60,
    "useGlobalSources": true,
    "sources": [],
    "schemaTargets": ""
  }
}

Skills

{
  "id": "my-skill",
  "type": "skill",
  "name": "My Skill",
  "summary": "Short description",
  "tags": ["tag1", "tag2"],
  "prompt": "Description of when to use this skill and what it does..."
}

Skill Bundles

Use skill-bundle to describe packs that need a bootstrap, shared install, or cross-skill workflow (e.g., Superpowers). Keep bundle metadata lightweight and put detailed instructions in docs.

{
  "id": "superpowers-bundle",
  "type": "skill-bundle",
  "name": "Superpowers",
  "summary": "Workflow bundle of interdependent skills and bootstraps.",
  "version": "x.y.z",
  "docs": { "url": "https://github.com/obra/superpowers" },
  "skills": ["superpowers:brainstorming", "superpowers:writing-plans"],
  "install": {
    "method": "manual",
    "instructions": "Claude Code: /plugin install superpowers@superpowers-marketplace\nCodex: clone https://github.com/obra/superpowers into ~/.codex/superpowers and add the AGENTS bootstrap.",
    "notes": "Codex CLI currently requires a CJS/ESM fix for skills-core import."
  },
  "backends": ["claude-code", "codex-cli"]
}

External Skill Packs (Normalization)

When adding skills from external repos (Superpowers, Automattic/agent-skills):

1. Inspect the repo to identify SKILL.md files or skill.yaml.
2. Extract name/summary and convert each to templates[] entries (type: "skill").
3. Add a skill-bundle entry if the pack requires shared bootstrap or workflow.
4. Inject a compatibility preamble for multi-backend usage (tool mapping + fallbacks).
5. Update the desktop app types/UI if you add a new template type.

Example conversion:

{
  "id": "wp-block-development",
  "type": "skill",
  "name": "WP Block Development",
  "summary": "Gutenberg blocks: block.json, attributes, rendering, deprecations.",
  "tags": ["wordpress", "gutenberg", "blocks"],
  "prompt": "Use when developing WordPress (Gutenberg) blocks..."
}

Multi-Backend Compatibility

For Claude Code, Codex, and OpenAI Agents, include deterministic tool mapping:

• Define canonical tools (read, write, shell, mcp, plan)
• Map to backend-specific names (ex: TodoWrite -> update_plan, Bash -> shell_command)
• Note unsupported features (subagents, web search, image support) in the prompt

When a skill is backend-specific, declare the scope in docs or tags and provide fallback instructions for other backends.

Validation Checklist

After editing registry.json:

1. Validate JSON syntax:

   node -e "JSON.parse(require('fs').readFileSync('registry.json', 'utf8')); console.log('JSON valid')"
   

2. Update version fields:

   • Increment version at the top (semver: major.minor.patch)
   • Update updatedAt timestamp

3. Check required fields:

   • MCP entries: id, name, summary, runtime, install
   • Templates: id, type, name, summary
   • requires values match entries[].id (no mcp: prefixes)

4. Update app types when adding new template types:

   • apps/desktop/src/lib/registry.ts (type unions)
   • apps/desktop/src/pages/Discover.tsx (filters and labels)

Desktop App Code References

The registry is consumed by:

• apps/desktop/src/lib/registry.ts - TypeScript types
• apps/desktop/src/pages/Discover.tsx - Template display
• apps/desktop/src/pages/McpStore.tsx - MCP management
• apps/desktop/DISCOVER.md - IA reference and registry model notes
• apps/desktop/CLAUDE.md - Registry update instructions

Key type definitions:

// RegistryTemplate types
type: "heartbeat-task" | "assistant-prompt" | "assistant-preset" | "skill" | "skill-bundle" | "plugin"

// Discover.tsx filters:
// - Agent Templates: templates.filter(t => t.type === "assistant-prompt")
// - Skills: templates.filter(t => t.type === "skill" or "skill-bundle")
// - Prompt Templates: types "assistant-prompt", "heartbeat-task", "plugin"

Common Mistakes to Avoid

1. Putting skills in wrong location: Skills go in templates[] with type: "skill", not a separate skills[] array
2. Missing type field: Templates must have a type field
3. Invalid JSON: Always validate after editing
4. Stale version: Remember to bump version and updatedAt
5. Interactive install commands: Use npx -y ... to avoid prompts
6. Wrong requires syntax: Use plain MCP IDs (no mcp: prefix)
7. Docs pointing to local paths: docs.path must be repo-relative and committed
8. New template types without UI support: Update registry.ts + Discover.tsx