@capekai/core 1.0.0

package/src/session-search/host.ts

@@ -0,0 +1,56 @@
+import type { Session, Workspace } from '@capekai/types';
+
+export interface SearchMessageResult {
+  messageId: string;
+  sessionId: string;
+  workspaceId: string;
+  role: string;
+  content: string;
+  timestamp: number;
+  sessionTitle: string | null;
+  rank: number;
+}
+
+export interface SessionSearchHost {
+  getWorkspace(id: string): Promise<Workspace | null>;
+  getSession(id: string): Promise<Session | null>;
+  listWorkspaceSessions(workspaceId: string): Promise<Session[]>;
+  listAgentSessions(agentId: string, limit: number): Promise<Session[]>;
+  countSessionMessages(sessionId: string): Promise<number>;
+  searchMessages(options: {
+    query: string;
+    workspaceId?: string;
+    agentId?: string;
+    sessionId?: string;
+    roleFilter: string[];
+    limit: number;
+    sort: 'relevance' | 'newest' | 'oldest';
+  }): Promise<SearchMessageResult[]>;
+  countMessagesBefore(sessionId: string, timestamp: number): Promise<number>;
+  countMessagesAfter(sessionId: string, timestamp: number): Promise<number>;
+  getLatestMessage(sessionId: string): Promise<{ id: string; timestamp: number } | null>;
+  getMessage(messageId: string, sessionId: string): Promise<{ id: string; timestamp: number } | null>;
+  listMessagesBefore(sessionId: string, timestamp: number, limit: number): Promise<Array<{ id: string; role: string; timestamp: number }>>;
+  listMessagesAfter(sessionId: string, timestamp: number, limit: number): Promise<Array<{ id: string; role: string; timestamp: number }>>;
+  getMessageSummary(messageId: string): Promise<{ role: string; timestamp: number; content: string; toolName: string } | null>;
+}
+
+const emptyHost: SessionSearchHost = {
+  getWorkspace: async () => null,
+  getSession: async () => null,
+  listWorkspaceSessions: async () => [],
+  listAgentSessions: async () => [],
+  countSessionMessages: async () => 0,
+  searchMessages: async () => [],
+  countMessagesBefore: async () => 0,
+  countMessagesAfter: async () => 0,
+  getLatestMessage: async () => null,
+  getMessage: async () => null,
+  listMessagesBefore: async () => [],
+  listMessagesAfter: async () => [],
+  getMessageSummary: async () => null,
+};
+
+let host = emptyHost;
+export function configureSessionSearchHost(value?: SessionSearchHost): void { host = value ?? emptyHost; }
+export function getSessionSearchHost(): SessionSearchHost { return host; }

package/src/session-search/index.ts

@@ -0,0 +1,23 @@
+export * from './host';
+export * from './session-search-tool';
+
+export const SESSION_SEARCH_GUIDANCE = `You can use session_search to recall prior conversation details from the current workspace or current session archive.
+Use it when the user references past work, says "we did this before", asks what happened earlier, or when compaction may have removed exact details from active context.
+
+Three modes:
+1. List mode (action: "list"): Enumerate recent sessions in the workspace. Returns session IDs, titles, and message counts. Use this to discover what exists.
+2. Search mode (provide "query"): Full-text search across messages.
+3. Read mode (provide "sessionId"): Read the latest context from a session. Optionally provide "aroundMessageId" to anchor at a specific message.
+
+Search scopes:
+- scope="current_session": Search only this session archive.
+- scope="workspace": Search all sessions in the current workspace (default).
+- scope="agent": Search YOUR past sessions across ALL workspaces. Use this to recall work from other projects.
+
+Typical workflow: list sessions, then read a session's latest context, then search for specific keywords if needed.
+Prefer scope="current_session" when looking for details from earlier in this same conversation.
+Prefer scope="workspace" when looking for related previous sessions in this workspace.
+Use scope="agent" when you need to recall work from a different project.
+Do not ask the user to repeat information until you have searched likely prior context.
+Search results are snippets; use read mode with sessionId to get full surrounding context.
+Default search focuses on user/assistant messages. Include tool results only when exact tool output, commands, errors, or logs are relevant.`;

package/src/session-search/session-search-tool.ts

@@ -0,0 +1,151 @@
+import type { PermissionAsk } from '@capekai/tool'
+import type { PermissionRiskLevel } from '@capekai/tool'
+import type { Session } from '@capekai/types';
+import { getSessionSearchHost, type SessionSearchHost } from './host';
+
+export const sessionSearchToolDefinition = {
+  name: 'session_search',
+  description: `Search prior conversation messages, list recent sessions, or read session context from the current workspace.
+Use it to recall past work, find earlier discussions, or retrieve details that may have been compacted away from active context.
+Three modes:
+1. List mode (provide "action": "list"): List recent sessions in the workspace with their IDs, titles, and message counts. Use this to discover what sessions exist before reading.
+2. Search mode (provide "query"): Full-text search across messages in the workspace or current session.
+3. Read-around mode (provide "sessionId", optionally "aroundMessageId"): Read messages surrounding a specific message. If "aroundMessageId" is omitted, reads the latest messages in that session.
+
+Typical workflow: list sessions → read a session's latest context → search for specific keywords if needed.`,
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      action: { type: 'string' as const, enum: ['list', 'search', 'read'], description: 'The action to perform. "list": enumerate recent sessions. "search": full-text search (default if query provided). "read": read session context. Defaults to "search" if query is provided, "read" if sessionId is provided.' },
+      query: { type: 'string' as const, description: 'Search query for full-text search. Triggers search mode.' },
+      scope: { type: 'string' as const, enum: ['current_session', 'workspace', 'agent'], description: 'Search scope. "current_session" searches only the current session archive. "workspace" searches all sessions in the workspace. "agent" searches YOUR past sessions across ALL workspaces. Defaults to "workspace".' },
+      sessionId: { type: 'string' as const, description: 'Session ID for read-around mode. Use "list" action first to discover session IDs. Must belong to the current workspace or (for agents) be an agent-owned session.' },
+      aroundMessageId: { type: 'string' as const, description: 'Anchor message ID for read-around mode. Returns surrounding messages. If omitted, reads the latest messages in the session.' },
+      limit: { type: 'number' as const, description: 'Max results for search mode, or max sessions for list mode. Default 5, max 20.' },
+      window: { type: 'number' as const, description: 'Number of messages to return around the anchor in read-around mode. Default 8, max 25.' },
+      roleFilter: { type: 'array' as const, items: { type: 'string' as const, enum: ['user', 'assistant', 'tool'] }, description: 'Roles to include in results. Defaults to ["user", "assistant"] unless workspace includes tool results.' },
+      sort: { type: 'string' as const, enum: ['relevance', 'newest', 'oldest'], description: 'Sort order for search results. Defaults to "relevance".' },
+    },
+  },
+  timeout: 15000,
+};
+
+const MAX_CONTENT_LENGTH = 2000;
+export interface SessionListEntry { id: string; title: string; messageCount: number; updatedAt: string }
+export interface SessionSearchResult {
+  success: boolean;
+  mode: 'list' | 'search' | 'read';
+  title: string;
+  sessions?: SessionListEntry[];
+  query?: string;
+  scope?: string;
+  results?: Array<{ sessionId: string; sessionTitle: string | null; messageId: string; role: string; timestamp: number; snippet: string; rank: number; messagesBefore: number; messagesAfter: number }>;
+  sessionId?: string;
+  sessionTitle?: string | null;
+  anchorMessageId?: string;
+  anchorInferred?: boolean;
+  messagesBefore?: number;
+  messagesAfter?: number;
+  messages?: Array<{ id: string; role: string; timestamp: number; content: string }>;
+  error?: string;
+}
+
+/** Unscoped execution path: reads the configured module-level host, exactly
+ * like the pre-C5 tool. */
+export async function executeSessionSearchTool(input: Record<string, unknown>, workspaceId: string, currentSessionId: string, includeToolResults: boolean, risk: PermissionRiskLevel, askFn?: (ask: PermissionAsk) => Promise<unknown>, agentId?: string | null): Promise<SessionSearchResult> {
+  return runSessionSearch(getSessionSearchHost(), input, workspaceId, currentSessionId, includeToolResults, risk, askFn, agentId);
+}
+
+/** Composed execution path: the domain plugin captures the process-scoped
+ * host service at setup and passes it here, so composed execution never
+ * reads the mutable module-global host accessor. */
+export async function executeSessionSearchToolWithHost(host: SessionSearchHost, input: Record<string, unknown>, workspaceId: string, currentSessionId: string, includeToolResults: boolean, risk: PermissionRiskLevel, askFn?: (ask: PermissionAsk) => Promise<unknown>, agentId?: string | null): Promise<SessionSearchResult> {
+  return runSessionSearch(host, input, workspaceId, currentSessionId, includeToolResults, risk, askFn, agentId);
+}
+
+async function runSessionSearch(host: SessionSearchHost, input: Record<string, unknown>, workspaceId: string, currentSessionId: string, includeToolResults: boolean, risk: PermissionRiskLevel, askFn?: (ask: PermissionAsk) => Promise<unknown>, agentId?: string | null): Promise<SessionSearchResult> {
+  const workspace = await host.getWorkspace(workspaceId);
+  if (!workspace) return { success: false, mode: 'search', title: 'Workspace not found', error: 'Workspace not found' };
+  const query = input.query as string | undefined;
+  const scope = (input.scope as string) || 'workspace';
+  const sessionId = input.sessionId as string | undefined;
+  const action = (input.action as string) || (query ? 'search' : sessionId ? 'read' : 'search');
+  if (scope === 'agent' && !agentId) {
+    return { success: false, mode: action === 'read' ? 'read' : action === 'list' ? 'list' : 'search', title: 'Agent scope unavailable', error: 'Agent scope requires an agent session' };
+  }
+  if (action === 'list') return executeList(host, workspaceId, currentSessionId, input, scope, agentId);
+  if (risk !== 'none' && askFn) {
+    const approved = await askFn({ type: 'permission', question: query ? `Allow searching workspace sessions for "${query.slice(0, 100)}"?` : 'Allow reading session context?', description: `Tool: session_search\nWorkspace: ${workspace.name}${query ? `\nQuery: ${query.slice(0, 200)}` : ''}\nScope: ${scope}`, risk, resource: 'session', action: 'read' });
+    if (!approved) return { success: false, mode: 'search', title: 'Permission denied', error: 'USER_REJECTION' };
+  }
+  if (query) return executeSearch(host, query, scope, workspaceId, currentSessionId, includeToolResults, input, agentId);
+  if (sessionId) return executeReadAround(host, sessionId, input.aroundMessageId as string | undefined, workspaceId, input, agentId);
+  return { success: false, mode: 'search', title: 'Invalid arguments', error: 'Provide "action": "list" to enumerate sessions, "query" for search mode, or "sessionId" for read-around mode.' };
+}
+
+async function executeList(host: SessionSearchHost, workspaceId: string, currentSessionId: string, input: Record<string, unknown>, scope: string, agentId?: string | null): Promise<SessionSearchResult> {
+  const limit = Math.min(Math.max((input.limit as number) || 10, 1), 20);
+  let sessions: Session[];
+  let label: string;
+  if (scope === 'agent' && agentId) {
+    sessions = await host.listAgentSessions(agentId, limit);
+    label = 'agent sessions (cross-workspace)';
+  } else {
+    sessions = await host.listWorkspaceSessions(workspaceId);
+    label = scope === 'current_session' ? 'current session' : 'workspace';
+  }
+  const limited = sessions.slice(0, limit);
+  if (limited.length === 0) return { success: true, mode: 'list', title: 'No sessions found', sessions: [] };
+  const entries: SessionListEntry[] = [];
+  for (const session of limited) {
+    entries.push({ id: session.id, title: session.title || '(untitled)', messageCount: await host.countSessionMessages(session.id), updatedAt: session.updatedAt, ...(session.id === currentSessionId && { isCurrent: true }) } as SessionListEntry);
+  }
+  return { success: true, mode: 'list', title: `${sessions.length} session${sessions.length === 1 ? '' : 's'} (${label})`, sessions: entries };
+}
+
+async function executeSearch(host: SessionSearchHost, query: string, scope: string, workspaceId: string, currentSessionId: string, includeTools: boolean, input: Record<string, unknown>, agentId?: string | null): Promise<SessionSearchResult> {
+  const limit = Math.min(Math.max((input.limit as number) || 5, 1), 20);
+  const sort = ((input.sort as string) || 'relevance') as 'relevance' | 'newest' | 'oldest';
+  let roles = (input.roleFilter as string[] | undefined) ?? (includeTools ? ['user', 'assistant', 'tool'] : ['user', 'assistant']);
+  roles = roles.filter((role) => ['user', 'assistant', 'tool'].includes(role));
+  if (roles.length === 0) roles = ['user', 'assistant'];
+  const results = await host.searchMessages({ query, workspaceId: scope === 'agent' ? undefined : workspaceId, agentId: scope === 'agent' ? agentId ?? undefined : undefined, sessionId: scope === 'current_session' ? currentSessionId : undefined, roleFilter: roles, limit, sort });
+  if (results.length === 0) return { success: true, mode: 'search', title: 'No prior context found', query, scope, results: [] };
+  const mappedResults: NonNullable<SessionSearchResult['results']> = [];
+  for (const result of results) {
+    mappedResults.push({ sessionId: result.sessionId, sessionTitle: result.sessionTitle, messageId: result.messageId, role: result.role, timestamp: result.timestamp, snippet: result.content, rank: result.rank, messagesBefore: await host.countMessagesBefore(result.sessionId, result.timestamp), messagesAfter: await host.countMessagesAfter(result.sessionId, result.timestamp) });
+  }
+  return {
+    success: true, mode: 'search', title: `Searched ${scope === 'current_session' ? 'current session' : scope === 'agent' ? 'agent sessions (cross-workspace)' : 'workspace sessions'}`, query, scope,
+    results: mappedResults,
+  };
+}
+
+async function executeReadAround(host: SessionSearchHost, sessionId: string, anchorId: string | undefined, workspaceId: string, input: Record<string, unknown>, agentId?: string | null): Promise<SessionSearchResult> {
+  const session = await host.getSession(sessionId);
+  if (!session) return { success: false, mode: 'read', title: 'Session not found', error: 'Session not found' };
+  if (session.workspaceId !== workspaceId && !(agentId && session.agentId === agentId)) return { success: false, mode: 'read', title: 'Access denied', error: 'Session does not belong to current workspace or agent' };
+  let inferred = false;
+  let anchor = anchorId ? await host.getMessage(anchorId, sessionId) : null;
+  if (!anchorId) {
+    anchor = await host.getLatestMessage(sessionId);
+    inferred = true;
+    if (!anchor) return { success: false, mode: 'read', title: 'Empty session', error: 'Session has no messages' };
+  }
+  if (!anchor) return { success: false, mode: 'read', title: 'Message not found', error: 'Anchor message not found in session' };
+  const window = Math.min(Math.max((input.window as number) || 8, 1), 25);
+  const half = Math.floor(window / 2);
+  const before = await host.listMessagesBefore(sessionId, anchor.timestamp, half);
+  const after = await host.listMessagesAfter(sessionId, anchor.timestamp, half);
+  const ids = [...before.reverse().map((message) => message.id), anchor.id, ...after.map((message) => message.id)];
+  const messages: NonNullable<SessionSearchResult['messages']> = [];
+  for (const id of ids) {
+    const summary = await host.getMessageSummary(id);
+    if (!summary) continue;
+    let text = summary.content;
+    if (summary.toolName) text = text ? `${text} [tool: ${summary.toolName}]` : `[tool: ${summary.toolName}]`;
+    if (text.length > MAX_CONTENT_LENGTH) text = `${text.slice(0, MAX_CONTENT_LENGTH)}...`;
+    messages.push({ id, role: summary.role, timestamp: summary.timestamp, content: text || '(no text content)' });
+  }
+  return { success: true, mode: 'read', title: inferred ? 'Read latest session context' : 'Read session context', sessionId, sessionTitle: session.title, anchorMessageId: anchor.id, ...(inferred && { anchorInferred: true }), messagesBefore: await host.countMessagesBefore(sessionId, anchor.timestamp), messagesAfter: await host.countMessagesAfter(sessionId, anchor.timestamp), messages };
+}

package/src/skills/index.ts

@@ -0,0 +1,3 @@
+export * from './registry';
+export * from './skill-tool';
+export * from './skill-manage-tool';

package/src/skills/registry.ts

@@ -0,0 +1,63 @@
+import { existsSync } from 'fs';
+import { readdir, readFile } from 'fs/promises';
+import { join } from 'path';
+import { getHostLayout } from '../runtime/host-layout';
+import type { SkillInfo } from '@capekai/types';
+
+function parseFrontmatter(raw: string): { frontmatter: Record<string, unknown>; content: string } {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, content: raw };
+  const frontmatter: Record<string, unknown> = {};
+  for (const line of match[1].split('\n')) {
+    const colon = line.indexOf(':');
+    if (colon > 0) frontmatter[line.slice(0, colon).trim()] = line.slice(colon + 1).trim().replace(/^['"]|['"]$/g, '');
+  }
+  return { frontmatter, content: match[2] };
+}
+
+export async function scanSkillsDir(skillsDir: string): Promise<SkillInfo[]> {
+  if (!existsSync(skillsDir)) return [];
+  const skills: SkillInfo[] = [];
+  try {
+    for (const folder of await readdir(skillsDir, { withFileTypes: true })) {
+      if (!folder.isDirectory()) continue;
+      const location = join(skillsDir, folder.name, 'SKILL.md');
+      try {
+        if (!existsSync(location)) continue;
+        const { frontmatter, content } = parseFrontmatter(await readFile(location, 'utf-8'));
+        if (!frontmatter.name || !frontmatter.description) {
+          console.warn(`Invalid SKILL.md in ${folder.name}: missing name or description`);
+          continue;
+        }
+        skills.push({ name: frontmatter.name as string, description: frontmatter.description as string, location, content: content.trim(), userInvocable: frontmatter['user-invocable'] !== false });
+      } catch (error: unknown) {
+        console.warn(`Failed to read SKILL.md in ${folder.name}:`, error);
+      }
+    }
+  } catch (error: unknown) {
+    console.error('Failed to scan skills directory:', error);
+  }
+  return skills;
+}
+export const scanSkillsFromDir = scanSkillsDir;
+export async function scanSkills(workspacePath: string, agentSkillsDir?: string): Promise<SkillInfo[]> {
+  const skills = await scanSkillsDir(getHostLayout().workspaceSkillsDir(workspacePath));
+  if (agentSkillsDir) {
+    const names = new Set(skills.map((skill) => skill.name));
+    for (const skill of await scanSkillsDir(agentSkillsDir)) if (!names.has(skill.name)) skills.push(skill);
+  }
+  return skills;
+}
+export async function getSkill(name: string, workspacePath: string, agentSkillsDir?: string): Promise<SkillInfo | null> {
+  return (await scanSkills(workspacePath, agentSkillsDir)).find((skill) => skill.name === name) ?? null;
+}
+export const listSkills = scanSkills;
+export async function getAvailableSkills(workspacePath: string, allowed: string[] | null | undefined, agentSkillsDir?: string): Promise<SkillInfo[]> {
+  const all = await scanSkills(workspacePath, agentSkillsDir);
+  if (allowed === undefined || allowed === null) return all;
+  if (allowed.length === 0) return [];
+  return all.filter((skill) => allowed.includes(skill.name));
+}
+export function formatSkillsList(skills: SkillInfo[]): string {
+  return skills.length === 0 ? 'No skills are currently available.' : skills.map((skill) => `- **${skill.name}**: ${skill.description}`).join('\n');
+}

package/src/skills/skill-manage-tool.ts

@@ -0,0 +1,205 @@
+import { existsSync } from 'fs';
+import { mkdir, readFile, readdir, rm, writeFile } from 'fs/promises';
+import { join } from 'path';
+import type { PermissionAsk } from '@capekai/tool';
+import { PermissionRiskLevel } from '@capekai/tool';
+import { scanSkillsFromDir } from './registry';
+
+type SkillManageAction = 'list' | 'create' | 'update' | 'patch' | 'delete';
+export interface SkillManageResult {
+  success: boolean;
+  title?: string;
+  action?: SkillManageAction;
+  name?: string;
+  description?: string;
+  path?: string;
+  summary?: string;
+  skills?: Array<{ name: string; description: string }>;
+  error?: string;
+}
+
+function sanitizeSkillName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/-+/g, '-').replace(/^-+|-+$/g, '');
+}
+function validateSkillName(name: string): string | null {
+  if (!name || name.trim().length === 0) return 'Skill name cannot be empty.';
+  if (name.includes('/') || name.includes('\\')) return 'Skill name cannot contain path separators.';
+  if (name.startsWith('.')) return 'Skill name cannot start with a dot.';
+  if (name.includes('..')) return 'Skill name cannot contain "..".';
+  return null;
+}
+const frontmatter = (name: string, description: string) => `---\nname: ${name}\ndescription: ${description}\n---\n`;
+const skillDir = (root: string, name: string) => join(root, name);
+const skillPath = (root: string, name: string) => join(skillDir(root, name), 'SKILL.md');
+
+async function resolveSkillFolder(rawName: string, root: string): Promise<{ folderName: string; skillMdPath: string } | null> {
+  const safeName = sanitizeSkillName(rawName);
+  const direct = skillPath(root, safeName);
+  if (existsSync(direct)) return { folderName: safeName, skillMdPath: direct };
+  if (!existsSync(root)) return null;
+  try {
+    for (const folder of await readdir(root, { withFileTypes: true })) {
+      if (!folder.isDirectory()) continue;
+      const path = join(root, folder.name, 'SKILL.md');
+      if (!existsSync(path)) continue;
+      if (folder.name.toLowerCase() === safeName.toLowerCase()) return { folderName: folder.name, skillMdPath: path };
+      try {
+        const match = (await readFile(path, 'utf-8')).match(/^---\n([\s\S]*?)\n---\n?/);
+        const name = match?.[1].match(/^name:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '').trim().toLowerCase();
+        if (name === safeName.toLowerCase()) return { folderName: folder.name, skillMdPath: path };
+      } catch {
+        continue;
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+async function availableNames(root: string): Promise<string[]> {
+  return (await scanSkillsFromDir(root)).map((skill) => skill.name);
+}
+
+export async function buildSkillManageToolDescription(root: string): Promise<string> {
+  const skills = await scanSkillsFromDir(root);
+  const lines = [
+    'Create, update, patch, delete, or list workspace skills.', '',
+    'Workspace skills are reusable procedures and workflows stored as SKILL.md files in .agents/skills/.', '',
+    'Actions:',
+    '- list: List all existing skills with their names and descriptions. No other parameters needed.',
+    '- create: Create a new skill. Requires name, description, and content (markdown body).',
+    '- update: Replace a skill\'s full body and optionally update description. Requires name and content.',
+    '- patch: Targeted string replacement in a skill\'s SKILL.md. Requires name, oldString, newString.',
+    '- delete: Remove a skill entirely. Requires name only.', '',
+    'Skill bodies should be procedural: When to Use, Procedure steps, Pitfalls, Verification.', '',
+  ];
+  if (skills.length > 0) {
+    lines.push('Existing skills in this workspace:');
+    for (const skill of skills) lines.push(`- ${skill.name}: ${skill.description}`);
+    lines.push('', 'For patch/update, use the exact name shown above. Skill names are matched case-insensitively.');
+  } else lines.push('No skills exist yet. Use create to make the first one.');
+  return lines.join('\n');
+}
+
+export const skillManageToolDefinition = {
+  name: 'skill_manage',
+  description: `Create, update, patch, or delete workspace skills.
+
+Workspace skills are reusable procedures and workflows stored as SKILL.md files in .agents/skills/.
+
+Actions:
+- list: List all existing skills with their names and descriptions. No other parameters needed.
+- create: Create a new skill. Requires name, description, and content (markdown body).
+- update: Replace a skill's full body and optionally update description. Requires name and content.
+- patch: Targeted string replacement in a skill's SKILL.md. Requires name, oldString, newString.
+- delete: Remove a skill entirely. Requires name only.
+
+Skill bodies should be procedural: When to Use, Procedure steps, Pitfalls, Verification.`,
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      action: { type: 'string' as const, enum: ['list', 'create', 'update', 'patch', 'delete'], description: 'The action to perform.' },
+      name: { type: 'string' as const, description: 'Skill name (will be normalized to a safe slug). Matched case-insensitively against existing skills.' },
+      description: { type: 'string' as const, description: 'Concise trigger/use description for the skill. Required for create. Optional for update/patch.' },
+      content: { type: 'string' as const, description: 'Markdown body for create/update actions. Not full frontmatter — just the body.' },
+      oldString: { type: 'string' as const, description: 'Exact text to find for patch action. Must match exactly once. Load the skill first to see the exact content.' },
+      newString: { type: 'string' as const, description: 'Replacement text for patch action.' },
+    },
+    required: ['action'],
+  },
+  timeout: 10000,
+};
+
+export async function executeSkillManageTool(input: Record<string, unknown>, root: string, risk: PermissionRiskLevel, askFn?: (ask: PermissionAsk) => Promise<unknown>): Promise<SkillManageResult> {
+  const action = input.action as SkillManageAction;
+  const rawName = input.name as string;
+  const description = input.description as string | undefined;
+  const content = input.content as string | undefined;
+  const oldString = input.oldString as string | undefined;
+  const newString = input.newString as string | undefined;
+  if (!['list', 'create', 'update', 'patch', 'delete'].includes(action)) return { success: false, error: 'Invalid action. Must be list, create, update, patch, or delete.' };
+  if (action === 'list') {
+    const skills = await scanSkillsFromDir(root);
+    if (skills.length === 0) return { success: true, title: 'No skills found', action: 'list', summary: 'No skills exist in this workspace yet.', skills: [] };
+    return { success: true, title: `${skills.length} skill${skills.length === 1 ? '' : 's'} found`, action: 'list', summary: skills.map((skill) => `${skill.name}: ${skill.description}`).join('\n'), skills: skills.map(({ name, description: value }) => ({ name, description: value })) };
+  }
+  if (typeof rawName !== 'string') return { success: false, error: 'Skill name cannot be empty.' };
+  if (description !== undefined && typeof description !== 'string') return { success: false, error: 'description must be a string.' };
+  if (content !== undefined && typeof content !== 'string') return { success: false, error: 'content must be a string.' };
+  if (oldString !== undefined && typeof oldString !== 'string') return { success: false, error: 'oldString must be a string.' };
+  if (newString !== undefined && typeof newString !== 'string') return { success: false, error: 'newString must be a string.' };
+  const nameError = validateSkillName(rawName);
+  if (nameError) return { success: false, error: nameError };
+  const safeName = sanitizeSkillName(rawName);
+  if (!safeName) return { success: false, error: 'Skill name is invalid after normalization.' };
+  if (risk !== 'none' && askFn) {
+    const approved = await askFn({ type: 'permission', question: `Allow skill ${action}: ${safeName}?`, description: `Action: ${action}\nSkill: ${safeName}${description ? `\nDescription: ${description.slice(0, 200)}` : ''}${content ? `\nContent: ${content.slice(0, 200)}` : ''}`, risk, resource: 'file', action: 'write', paths: [`${safeName}/SKILL.md`] });
+    if (!approved) return { success: false, error: 'USER_REJECTION' };
+  }
+
+  if (action === 'create') {
+    if (!description) return { success: false, error: 'description is required for create action.' };
+    if (!content) return { success: false, error: 'content is required for create action.' };
+    const path = skillPath(root, safeName);
+    if (existsSync(path)) return { success: false, error: `Skill "${safeName}" already exists. Use update or patch instead.` };
+    await mkdir(skillDir(root, safeName), { recursive: true });
+    await writeFile(path, frontmatter(safeName, description) + '\n' + content + '\n', 'utf-8');
+    return { success: true, title: `Skill created: ${safeName}`, action, name: safeName, description, path: `${safeName}/SKILL.md`, summary: 'Created workspace skill.' };
+  }
+
+  const resolved = await resolveSkillFolder(rawName, root);
+  if (!resolved) {
+    const names = await availableNames(root);
+    return { success: false, error: `Skill "${rawName}" does not exist.${names.length ? ` Available skills: ${names.join(', ')}` : action === 'delete' ? '' : ' No skills exist yet. Use create first.'}` };
+  }
+  const relativePath = `${resolved.folderName}/SKILL.md`;
+  if (action === 'delete') {
+    await rm(skillDir(root, resolved.folderName), { recursive: true, force: true });
+    return { success: true, title: `Skill deleted: ${resolved.folderName}`, action, name: resolved.folderName, path: relativePath, summary: 'Removed workspace skill directory.' };
+  }
+  let existing: string;
+  try { existing = await readFile(resolved.skillMdPath, 'utf-8'); } catch { return { success: false, error: 'Failed to read existing skill file.' }; }
+
+  if (action === 'update') {
+    if (!content) return { success: false, error: 'content is required for update action.' };
+    const existingDescription = existing.match(/^description:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '') ?? '';
+    const existingName = existing.match(/^name:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '').trim() ?? resolved.folderName;
+    const effectiveDescription = description ?? existingDescription;
+    await writeFile(resolved.skillMdPath, frontmatter(existingName, effectiveDescription) + '\n' + content + '\n', 'utf-8');
+    return { success: true, title: `Skill updated: ${existingName}`, action, name: existingName, description: effectiveDescription, path: relativePath, summary: 'Replaced skill body.' };
+  }
+
+  if (!oldString) return { success: false, error: 'oldString is required for patch action.' };
+  if (newString === undefined || newString === null) return { success: false, error: 'newString is required for patch action.' };
+  const matches = existing.split(oldString).length - 1;
+  if (matches === 0) return { success: false, error: 'oldString not found in skill file. Load the skill via the "skill" tool first to see the exact content, then copy the exact text to oldString.' };
+  if (matches > 1) return { success: false, error: `oldString matched ${matches} locations. Provide a more specific oldString.` };
+  let patched = existing.replace(oldString, newString);
+  if (description) patched = patched.replace(/^(description:\s*).*$/m, `$1${description}`);
+  await writeFile(resolved.skillMdPath, patched, 'utf-8');
+  const resultName = patched.match(/^name:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '').trim() ?? resolved.folderName;
+  const resultDescription = description ?? patched.match(/^description:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '');
+  return { success: true, title: `Skill patched: ${resultName}`, action, name: resultName, description: resultDescription, path: relativePath, summary: 'Replaced one matching block.' };
+}
+
+export const SKILL_MANAGE_GUIDANCE = `You can create and update workspace skills using the skill_manage tool.
+Workspace skills are reusable procedures/workflows stored under .agents/skills in the current workspace.
+
+Use memory for compact durable facts.
+Use skill_manage for repeatable multi-step procedures, debugging workflows, conventions, and verification steps that are too procedural for MEMORY.md.
+
+When to create or update a skill:
+- After completing a complex reusable workflow.
+- After debugging through errors and discovering the working path.
+- When the user corrects your approach in a way that should affect future similar tasks.
+- When you discover workspace-specific procedures, pitfalls, commands, or verification steps.
+
+When not to create a skill:
+- For one-off facts or temporary context.
+- For secrets, credentials, raw logs, or large code dumps.
+- For obvious information already present in AGENTS.md or an existing skill.
+
+Before creating a new skill, consider whether an existing skill should be patched instead.
+Prefer patch over update for small changes.
+Keep skill descriptions concise and trigger-focused because descriptions are used to decide when to load a skill.
+Keep skill bodies procedural and verification-oriented.`;

package/src/skills/skill-tool.ts

@@ -0,0 +1,42 @@
+import type { Tool } from 'ai';
+import type { ToolDefinition } from '@capekai/tool';
+import { dirname } from 'path';
+import { pathToFileURL } from 'url';
+import { formatSkillsList, getAvailableSkills, getSkill } from './registry';
+
+export async function buildSkillToolDefinition(workspacePath: string, allowed: string[] | null | undefined, _sessionId: string, agentSkillsDir?: string): Promise<ToolDefinition | null> {
+  const skills = await getAvailableSkills(workspacePath, allowed, agentSkillsDir);
+  if (skills.length === 0) return null;
+  const examples = skills.slice(0, 3).map((skill) => `'${skill.name}'`).join(', ');
+  const description = [
+    'Load a specialized skill that provides domain-specific instructions and workflows.', '',
+    'When you recognize that a task matches one of the available skills listed below, use this tool to load the full skill instructions.', '',
+    'The skill will inject detailed instructions, workflows, and access to bundled resources (scripts, references, templates) into the conversation context.', '',
+    'Tool output includes a `<skill_content name="...">` block with the loaded content.', '',
+    'The following skills provide specialized sets of instructions for particular tasks.',
+    'Invoke this tool to load a skill when a task matches one of the available skills listed below:', '', formatSkillsList(skills),
+  ].join('\n');
+  return {
+    name: 'skill', description,
+    inputSchema: { type: 'object', properties: { name: { type: 'string', description: `The name of the skill from available_skills${examples ? ` (e.g., ${examples}, ...)` : ''}` } }, required: ['name'] },
+    outputSchema: { type: 'object', properties: { title: { type: 'string' }, output: { type: 'string' } } }, timeout: 5000,
+  };
+}
+
+export async function executeSkillTool(name: string, workspacePath: string, allowed: string[] | null | undefined, _sessionId: string, agentSkillsDir?: string): Promise<{ success: boolean; result?: unknown; error?: string }> {
+  const available = await getAvailableSkills(workspacePath, allowed, agentSkillsDir);
+  if (available.length === 0) return { success: false, error: 'No skills are available for this session.' };
+  const skill = await getSkill(name, workspacePath, agentSkillsDir);
+  if (!skill) return { success: false, error: `Skill "${name}" not found. Available skills: ${available.map((item) => item.name).join(', ') || 'none'}` };
+  if (!(allowed === undefined || allowed === null || allowed.includes(name))) return { success: false, error: `Skill "${name}" is not available for this session.` };
+  const directory = dirname(skill.location);
+  const output = [`<skill_content name="${skill.name}">`, `# Skill: ${skill.name}`, '', skill.content, '', `Base directory for this skill: ${pathToFileURL(directory).href}`, 'Relative paths in this skill (e.g., scripts/, references/) are relative to this base directory.', '</skill_content>'].join('\n');
+  return { success: true, result: { title: `Loaded skill: ${skill.name}`, output } };
+}
+
+export async function createSkillTool(workspacePath: string, allowed: string[] | null | undefined, sessionId: string, agentSkillsDir?: string): Promise<{ name: string; tool: Tool } | null> {
+  const definition = await buildSkillToolDefinition(workspacePath, allowed, sessionId, agentSkillsDir);
+  if (!definition) return null;
+  const { jsonSchema, tool } = await import('ai');
+  return { name: 'skill', tool: tool({ description: definition.description, inputSchema: jsonSchema(definition.inputSchema), execute: async (args: Record<string, unknown>) => executeSkillTool(args.name as string, workspacePath, allowed, sessionId, agentSkillsDir) }) };
+}