Skill Manager Plan

Overview

The Skill Manager controls which skills are available to bots (chatting via gate-runtime) and code sessions (Claude Code running in worktrees). Skills are categorized by scope and managed through profiles.

Key Distinction: Bot vs Code Session

A bot is Molly, Coder, Dev, etc. chatting through gate-runtime. It coordinates, delegates, manages tasks.

A code session (CS) is Claude Code spawned by a bot to write code in a worktree. It codes, commits, creates PRs.

They need different skills:

Context What it does Example skills
Bot Chat, coordinate, delegate, manage bot-communication, task-management, code-sessions
CS Write code, git ops, follow workflows gate-git, gate-gsd-guide, gate-project-config

GATE Skill Scopes

Every skill in gate/skills/ gets a scope field in its SKILL.md frontmatter:

---
name: "Gate Git"
scope: cs
description: "..."
---

Scope Assignments

Skill Scope Why
gate-git cs CS needs to push/pull/clone
gate-gsd-guide cs CS follows GSD workflow
gate-project-config cs CS reads project config
gate-github cs CS uses gh CLI for PRs/issues
gate-bot-communication bot Bot sends messages to other bots
gate-bot-registry bot Bot looks up other bots
gate-chat-history bot Bot reads chat history
gate-task-management bot Bot manages tasks
gate-code-sessions bot Bot spawns/manages CS sessions
gate-master-plan bot Bot runs planning conversations
gate-project-builder bot Bot orchestrates parallel CS
gate-caddy bot Bot manages reverse proxy
gate-cloudflare bot Bot manages DNS
gate-gmail bot Bot sends/reads email
gate-guest-channel bot Bot manages guest channels
gate-bot-browser bot Bot uses browser

How Scopes Are Read

buildSkillsSection() in config.ts already reads SKILL.md files. It will also parse the scope field from frontmatter:

Skill Profiles

A skill profile is a named, reusable collection of skills. Profiles can be attached to bots (for their CS sessions) or projects.

Skill Types in a Profile

Type Where it's installed How
skill ~/.claude/skills/<name>/ Write SKILL.md + files to bot home before CS starts
command ~/.claude/commands/<name>/ Write command .md files before CS starts
instruction Injected into CS CLAUDE.md Text block added during bootstrap

Marketplace plugins are left alone. Anthropic manages those. Users install them manually.

Profile Examples

"true-stack" profile:

"strict-testing" profile:

Database Schema

-- Skill profiles (reusable collections)
CREATE TABLE skill_profiles (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT,
  created_by TEXT,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
);

-- Skills within a profile
CREATE TABLE skill_profile_items (
  id TEXT PRIMARY KEY,
  profile_id TEXT NOT NULL REFERENCES skill_profiles(id) ON DELETE CASCADE,
  skill_type TEXT NOT NULL CHECK (skill_type IN ('skill', 'command', 'instruction')),
  name TEXT NOT NULL,
  content TEXT NOT NULL,
  sort_order INTEGER DEFAULT 0,
  created_at INTEGER NOT NULL
);

-- Bot <-> Profile assignments (for CS sessions the bot creates)
CREATE TABLE bot_skill_profiles (
  bot_id TEXT NOT NULL,
  profile_id TEXT NOT NULL REFERENCES skill_profiles(id) ON DELETE CASCADE,
  enabled INTEGER DEFAULT 1,
  created_at INTEGER NOT NULL,
  PRIMARY KEY (bot_id, profile_id)
);

-- Project <-> Profile assignments (Phase 2)
CREATE TABLE project_skill_profiles (
  project_id TEXT NOT NULL,
  profile_id TEXT NOT NULL REFERENCES skill_profiles(id) ON DELETE CASCADE,
  enabled INTEGER DEFAULT 1,
  created_at INTEGER NOT NULL,
  PRIMARY KEY (project_id, profile_id)
);

API Endpoints

# Profile CRUD
GET    /api/admin/skill-profiles           — List all profiles
POST   /api/admin/skill-profiles           — Create profile
GET    /api/admin/skill-profiles/:id       — Get profile with items
PUT    /api/admin/skill-profiles/:id       — Update profile name/description
DELETE /api/admin/skill-profiles/:id       — Delete profile

# Profile items
POST   /api/admin/skill-profiles/:id/items     — Add skill to profile
PUT    /api/admin/skill-profiles/:id/items/:itemId — Update item
DELETE /api/admin/skill-profiles/:id/items/:itemId — Remove item

# Bot assignments
GET    /api/bots/:botId/skill-profiles              — List bot's profiles
POST   /api/bots/:botId/skill-profiles              — Attach profile to bot
DELETE /api/bots/:botId/skill-profiles/:profileId   — Detach profile from bot

System Flow: What Happens When a CS Starts

Bot runs: gate cs start --name fixes --project org/repo
     │
     ▼
gate API creates worktree, spawns session
     │
     ▼
session-registry.ts → bootstrapRuntimeSession()
     │
     ├── 1. Read GATE cs-scoped skills (gate-git, gate-gsd-guide, etc.)
     │      → From gate/skills/*/SKILL.md where scope = "cs" or "both"
     │
     ├── 2. Read bot's assigned skill profiles from DB
     │      → bot_skill_profiles JOIN skill_profiles JOIN skill_profile_items
     │      → For each item:
     │          skill type  → write files to ~/.claude/skills/<name>/
     │          command type → write files to ~/.claude/commands/<name>/
     │          instruction type → collect text for CLAUDE.md
     │
     ├── 3. Read project's assigned skill profiles from DB (Phase 2)
     │      → Same logic as bot profiles
     │
     ├── 4. Generate/update the CS worktree's CLAUDE.md
     │      → Inject GATE cs-skills section
     │      → Inject instruction-type profile items
     │      → Preserve existing project CLAUDE.md if user-authored
     │
     └── 5. CS starts with everything in place

Important: Install BEFORE CS starts

Claude Code reads ~/.claude/skills/ and ~/.claude/commands/ at startup. Files must be in place before the process spawns. The bootstrap step handles this.

User Flows

Flow 1: Admin creates a skill profile (Dashboard)

1. Admin opens Dashboard → Skills (new top-level page)
2. Clicks "New Profile"
3. Names it "true-stack", adds description
4. Adds items:
   - Type: instruction, Content: "Use Bun runtime. Hono for HTTP. Drizzle for DB."
   - Type: skill, Name: "react-best-practices", Content: (SKILL.md content)
5. Saves profile
6. Goes to Bot detail → Skills tab
7. Attaches "true-stack" profile to Klara
8. Next time Klara starts a CS, it gets the true-stack skills

Flow 2: Admin manages bot skills (Dashboard)

1. Admin opens Dashboard → Bots → Klara → Skills tab
2. Sees three sections:
   a. "GATE Skills" — read-only list showing:
      - Bot skills (gate-bot-communication, etc.) — always on for Klara's chat
      - CS skills (gate-git, etc.) — always on for Klara's CS sessions
   b. "CS Skill Profiles" — profiles attached to Klara's CS sessions
      - [true-stack] ✓ enabled
      - [strict-testing] ✓ enabled
      - [+ Attach Profile] button
   c. "Quick Add" — create a one-off instruction/skill without making a full profile
3. Can toggle profiles on/off, attach new ones, detach existing ones

Flow 3: Bot manages skills via chat

User (V): "Add the true-stack profile to Coder's CS sessions"
Bot (Molly):
  1. Calls POST /api/bots/coder-bot-id/skill-profiles { profileId: "true-stack-id" }
  2. Responds: "Done. Coder's next CS will include the true-stack profile (Bun, Hono, Drizzle conventions)."

User (V): "Create a new skill profile called 'strict-linting' with instruction 'Run biome check before every commit'"
Bot (Molly):
  1. Calls POST /api/admin/skill-profiles { name: "strict-linting" }
  2. Calls POST /api/admin/skill-profiles/:id/items { type: "instruction", content: "Run biome check before every commit" }
  3. Responds: "Created profile 'strict-linting'. Want me to attach it to any bot?"

Flow 4: Bot starts a CS (System flow)

Molly runs: gate cs start --name fixes --project TRUEoriginal-com/TRUE-Verify --user claw-true-klara

System:
  1. gate API resolves project → /home/shared/true/projects/TRUE-Verify/develop
  2. Creates worktree at /home/shared/true/projects/TRUE-Verify/worktrees/fixes
  3. Calls bootstrapRuntimeSession() for Klara's bot

Bootstrap:
  4. Reads GATE skills with scope=cs → gate-git, gate-gsd-guide, gate-project-config, gate-github
  5. Reads Klara's profiles from DB → ["true-stack", "strict-testing"]
  6. For "true-stack" profile:
     - instruction item → queued for CLAUDE.md injection
     - skill "react-best-practices" → writes to /home/claw-true-klara/.claude/skills/react-best-practices/SKILL.md
  7. For "strict-testing" profile:
     - instruction item → queued for CLAUDE.md injection
     - command "run-tests" → writes to /home/claw-true-klara/.claude/commands/run-tests.md
  8. Checks TRUE-Verify project for profiles → (Phase 2, none yet)
  9. Generates CS CLAUDE.md:
     - If project has user-authored CLAUDE.md → append gate cs-skills + profile instructions as a section
     - If no CLAUDE.md → generate full one with gate cs-skills + profile instructions
  10. Spawns Claude Code → it reads ~/.claude/skills/, ~/.claude/commands/, and CLAUDE.md

Claude Code inside CS now has:
  - gate-git (push/pull)
  - gate-gsd-guide (workflow)
  - gate-project-config (project setup)
  - gate-github (gh CLI)
  - react-best-practices (from true-stack profile)
  - run-tests command (from strict-testing profile)
  - "Use Bun runtime. Hono for HTTP." instruction (from true-stack profile)
  - "Run biome check before every commit" instruction (from strict-testing profile)
  - TRUE-Verify's own CLAUDE.md content (if it exists)

Bot Flow: What the Bot Sees

Molly's workspace CLAUDE.md (auto-generated by generateClaudeMd()):

  ## Available Skills

  ### Bot Skills (for chat interactions)
  - gate-bot-communication — Send messages to other bots...
  - gate-bot-registry — Look up bot name/ID...
  - gate-task-management — Task management via gate CLI...
  - gate-code-sessions — Manage Claude Code sessions...
  - gate-master-plan — Build project plans...
  - gate-project-builder — Parallel CS orchestration...
  - gate-caddy — Reverse proxy management...
  - gate-cloudflare — DNS management...
  - gate-gmail — Gmail operations...
  - gate-guest-channel — Guest channel management...
  - gate-bot-browser — Chrome browser with VNC...

  ### CS Skills (injected into code sessions)
  - gate-git — Secure git proxy...
  - gate-gsd-guide — GSD workflow...
  - gate-project-config — Project configuration...
  - gate-github — GitHub CLI...

  ## AGENTS.md
  ...
  ## SOUL.md
  ...

Dashboard UI Structure

New top-level page: Skills

Dashboard sidebar:
  Bots
  Tasks
  Skills  <- NEW
  Admin

Skills page:

Bot detail -> Skills tab (rebuilt)

Three sections:

+---------------------------------------------+
| GATE Skills                           [info] |
|                                             |
| Bot Skills (always active in chat):         |
| o gate-bot-communication                    |
| o gate-task-management                      |
| o gate-code-sessions                        |
| o gate-master-plan                          |
| o ... (7 more)                              |
|                                             |
| CS Skills (always active in code sessions): |
| o gate-git                                  |
| o gate-gsd-guide                            |
| o gate-project-config                       |
| o gate-github                               |
+---------------------------------------------+
| CS Skill Profiles              [+ Attach]   |
|                                             |
| +-------------------------------------------+ |
| | true-stack                    [v] [edit]  | |
| | Bun, Hono, Drizzle, React conventions     | |
| | 1 skill, 1 instruction                    | |
| +-------------------------------------------+ |
| +-------------------------------------------+ |
| | strict-testing                [v] [edit]  | |
| | Full test suite before commits            | |
| | 1 command, 1 instruction                  | |
| +-------------------------------------------+ |
+---------------------------------------------+
| Quick Add                      [+ Add]      |
|                                             |
| Add a one-off instruction or skill to this  |
| bot's CS sessions without creating a full   |
| profile.                                    |
+---------------------------------------------+

Build Phases

Phase 1: Foundation (Bot Skill Manager)

Phase 2: Project Skills

Phase 3: Chat Interface

File Changes (Phase 1)

New files

Modified files