Files
waggle-os/packages/agent/src/skill-tools.ts
shumeiko.it 2e1999a3f6 refactor: remove self-learning and the optimizer package (P1.4)
Self-learning is excluded from the community edition (ADR-0004); the
project owner reworks it separately. Cost tracking stays.

- agent: delete behaviour evolution (evolve-schema, iterative GEPA,
  compose-evolution, evolution gates, orchestrator and deploy),
  improvement and correction detection, AgentLearning, the eval-dataset
  builder, optimization-capture and the agent_insights tool. Secret
  detection moves from eval-dataset to secret-patterns. The LLM wiring
  keeps only the Haiku adapter and judge call used by skill audit and
  hygiene, so @ax-llm/ax is now declared by agent instead of server.
- server: delete /api/evolution/*, the evolution and optimizer services,
  GEPA expansion of the first chat message, the prompt_optimization and
  monthly_assessment jobs, the idle-session reviewer and its
  session-reviewer persona, prompt injection of past corrections and
  thumbs-down recorded as correction signals. Existing job rows of the
  removed types are ignored, not deleted.
- core: delete OptimizationLogStore; stop re-exporting the improvement
  signal and evolution run stores.
- web: delete the Evolution screen and the two job types in the
  automation editor.
- delete packages/optimizer.

Also logs UF-027 (self-learning loops read data nothing collects) and
UF-028 (the Settings prompt-shape choice is ignored by chat).
2026-10-20 00:54:58 +02:00

900 lines
39 KiB
TypeScript
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Skill discovery, installation, and management tools for the agent.
*
* These tools let the agent dynamically discover capabilities it needs,
* install skills from the local filesystem or by creating them on the fly,
* and manage the active skill set — closing the gap to Claude Code's ecosystem.
*/
import * as fs from 'node:fs';
import * as path from 'node:path';
import type { ToolDefinition } from './tools.js';
import { SkillRecommender } from './skill-recommender.js';
import { searchCapabilities, validateInstallCandidate, type MarketplaceCandidate } from './capability-acquisition.js';
import { assessTrust, formatTrustSummary } from './trust-model.js';
import type { InstallAuditStore } from '@waggle/core';
// Type-only import — erased at runtime, so it does NOT reintroduce the
// agent ↔ marketplace runtime cycle that the lazy import below guards against.
import type { SecurityGate, MarketplacePackage } from '@waggle/marketplace';
// Lazy import to avoid circular dependency (agent ↔ marketplace)
let _SecurityGate: typeof SecurityGate | null = null;
async function getSecurityGate(): Promise<typeof SecurityGate> {
if (!_SecurityGate) {
const mod = await import('@waggle/marketplace');
_SecurityGate = mod.SecurityGate;
}
return _SecurityGate;
}
import { generateSkillMarkdown, type SkillTemplate } from './skill-creator.js';
import { redactSkillContent } from './skill-redaction.js';
import { writeSkill, deleteSkill as deleteSkillWrite } from './skill-write-service.js';
import {
parseSkillFrontmatter,
serializeFrontmatter,
nextScope,
SKILL_SCOPE_ORDER,
type SkillScope,
} from './skill-frontmatter.js';
import { autoExtractAndCreateSkill, type AutoExtractMessage } from './skill-autoextract.js';
import { retireStaleSkills } from './skill-retirement.js';
export interface SkillToolsDeps {
/** Path to ~/.waggle directory */
waggleHome: string;
/** Callback to reload skills into agent state after changes */
onSkillsChanged?: () => void;
/** Path to starter skills source directory (from @waggle/sdk) */
starterSkillsDir?: string;
/** Function to get current installed skills (for acquisition search) */
getInstalledSkills?: () => Array<{ name: string; content: string }>;
/** Native tool names (for acquisition search — avoids proposing install when a tool exists) */
nativeToolNames?: string[];
/** Audit store for recording install events (optional — degrades gracefully) */
auditStore?: InstallAuditStore;
/** Optional callback to search the marketplace catalog for capabilities */
searchMarketplace?: (query: string) => Promise<MarketplaceCandidate[]>;
/**
* Skills 2.0 gap E: promotion infrastructure. Each callback is optional.
* - getWorkspaceId / getTeamId resolve scope dirs dynamically at tool-call time.
*/
getWorkspaceId?: () => string | null;
getTeamId?: () => string | null;
/**
* Skills 2.0 gap A: session-message accessor for auto-extracting skills
* from repeated workflow patterns. When provided, enables the
* auto_extract_skills tool.
*/
getSessionMessages?: () => AutoExtractMessage[];
}
/**
* Skills 2.0 gap E: resolve the on-disk directory for a given scope.
* - personal: ~/.waggle/skills/
* - workspace: ~/.waggle/workspaces/{workspaceId}/skills/
* - team: ~/.waggle/teams/{teamId}/skills/
* - enterprise: ~/.waggle/enterprise/skills/
*
* Returns null when the required context (workspaceId, teamId) is missing.
*/
export function getSkillDirForScope(
waggleHome: string,
scope: SkillScope,
ctx: { workspaceId?: string | null; teamId?: string | null },
): string | null {
switch (scope) {
case 'personal':
return path.join(waggleHome, 'skills');
case 'workspace':
if (!ctx.workspaceId) return null;
return path.join(waggleHome, 'workspaces', ctx.workspaceId, 'skills');
case 'team':
if (!ctx.teamId) return null;
return path.join(waggleHome, 'teams', ctx.teamId, 'skills');
case 'enterprise':
return path.join(waggleHome, 'enterprise', 'skills');
}
}
export function createSkillTools(deps: SkillToolsDeps): ToolDefinition[] {
const { waggleHome, onSkillsChanged } = deps;
const skillsDir = path.join(waggleHome, 'skills');
const pluginsDir = path.join(waggleHome, 'plugins');
// Ensure directories exist
if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true });
if (!fs.existsSync(pluginsDir)) fs.mkdirSync(pluginsDir, { recursive: true });
return [
// 1. list_skills — Show all installed skills and plugins
{
name: 'list_skills',
description: 'List all installed skills and plugins. Skills extend your capabilities. Use this to check what you already have before searching for new ones.',
parameters: {
type: 'object',
properties: {
verbose: { type: 'boolean', description: 'Show full skill content (default: false, shows preview only)' },
},
},
execute: async (args) => {
const verbose = args.verbose as boolean ?? false;
// List skills
const skillFiles = fs.existsSync(skillsDir)
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'))
: [];
const skills = skillFiles.map(f => {
const name = f.replace(/\.md$/, '');
const content = fs.readFileSync(path.join(skillsDir, f), 'utf-8').trim();
return {
name,
type: 'skill' as const,
preview: verbose ? content : content.slice(0, 150) + (content.length > 150 ? '...' : ''),
size: content.length,
};
});
// List plugins
const pluginEntries = fs.existsSync(pluginsDir)
? fs.readdirSync(pluginsDir, { withFileTypes: true }).filter(d => d.isDirectory())
: [];
const plugins = pluginEntries.map(d => {
const manifestPath = path.join(pluginsDir, d.name, 'manifest.json');
let manifest: Record<string, unknown> = {};
if (fs.existsSync(manifestPath)) {
try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')); } catch { /* ignore */ }
}
return {
name: d.name,
type: 'plugin' as const,
description: (manifest.description as string) ?? 'No description',
version: (manifest.version as string) ?? 'unknown',
};
});
if (skills.length === 0 && plugins.length === 0) {
return 'No skills or plugins installed.\n\nYou can create a new skill with create_skill or search for existing ones with search_skills.';
}
let output = '';
if (skills.length > 0) {
output += `## Installed Skills (${skills.length})\n\n`;
for (const s of skills) {
output += `- **${s.name}** (${s.size} chars)\n ${s.preview}\n\n`;
}
}
if (plugins.length > 0) {
output += `## Installed Plugins (${plugins.length})\n\n`;
for (const p of plugins) {
output += `- **${p.name}** v${p.version} — ${p.description}\n`;
}
}
return output;
},
},
// 2. create_skill — Create a new skill on the fly (supports raw content OR structured template)
{
name: 'create_skill',
description: 'Create a new reusable skill from a workflow description or raw markdown content. Skills are loaded into your system prompt and persist across sessions. You can provide either raw `content` (markdown) or structured fields (`description`, `steps`, `tools`, `category`) and the skill markdown will be generated automatically.',
parameters: {
type: 'object',
properties: {
name: { type: 'string', description: 'Skill name (kebab-case, alphanumeric + hyphens, no spaces)' },
content: { type: 'string', description: 'Raw skill content in markdown. If provided, steps/tools/category are ignored.' },
description: { type: 'string', description: 'What this skill does (used when generating from structured input)' },
steps: { type: 'array', items: { type: 'string' }, description: 'Step-by-step workflow instructions' },
tools: { type: 'array', items: { type: 'string' }, description: 'Tools this skill uses (e.g., web_search, save_memory)' },
category: { type: 'string', description: 'Category (coding, research, writing, planning, knowledge, general)' },
},
required: ['name'],
},
execute: async (args) => {
const name = args.name as string;
const rawContent = args.content as string | undefined;
const description = args.description as string | undefined;
const steps = args.steps as string[] | undefined;
const tools = args.tools as string[] | undefined;
const category = args.category as string | undefined;
// Validate name
if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
return 'Error: Skill name must contain only letters, numbers, hyphens, and underscores.';
}
// Determine content: raw content takes priority, otherwise generate from template
let content: string;
if (rawContent) {
content = rawContent;
} else if (description && steps && steps.length > 0) {
const template: SkillTemplate = {
name,
description,
triggerPatterns: [],
steps,
tools: tools ?? [],
category: category ?? 'general',
};
content = generateSkillMarkdown(template);
} else {
return 'Error: Provide either "content" (raw markdown) or "description" + "steps" (structured input).';
}
// P5/D4(iii): one write path. The shared service strips secrets/paths,
// stamps agent provenance, records the install audit row, and fires the
// reload callback — same code the HTTP routes run.
const result = writeSkill(
{ skillsDir, auditStore: deps.auditStore, onChange: onSkillsChanged },
{ name, content, initiator: 'agent', source: 'chat' },
);
if (!result.ok) return `Error: ${result.error}`;
const redactions = result.redactions ?? [];
const redactNote = redactions.length
? `\n⚠️ Redacted ${redactions.length} secret(s)/path(s) before saving: ${redactions.join(', ')}.`
: '';
return `${result.existed ? 'Updated' : 'Created'} skill "${name}".${redactNote}\nLocation: ${result.path}\n\nThe skill is now active and will be included in your system prompt for all future messages.`;
},
},
// 3. delete_skill — Remove a skill
{
name: 'delete_skill',
description: 'Delete an installed skill by name.',
parameters: {
type: 'object',
properties: {
name: { type: 'string', description: 'Name of the skill to delete' },
},
required: ['name'],
},
execute: async (args) => {
const name = args.name as string;
// P5/D4(iii): one delete path — audits 'uninstalled' with agent provenance.
const result = deleteSkillWrite(
{ skillsDir, auditStore: deps.auditStore, onChange: onSkillsChanged },
{ name, initiator: 'agent', source: 'chat' },
);
if (!result.ok) return `Error: ${result.error}`;
return `Deleted skill "${name}".`;
},
},
// 4. read_skill — Read full content of a skill
{
name: 'read_skill',
description: 'Read the full content of an installed skill.',
parameters: {
type: 'object',
properties: {
name: { type: 'string', description: 'Name of the skill to read' },
},
required: ['name'],
},
execute: async (args) => {
const name = args.name as string;
if (name.includes('..') || name.includes('/') || name.includes('\\')) {
return 'Error: Invalid skill name.';
}
const filePath = path.join(skillsDir, `${name}.md`);
if (!fs.existsSync(filePath)) {
return `Error: Skill "${name}" not found.`;
}
return fs.readFileSync(filePath, 'utf-8');
},
},
// 5. search_skills — Search for skills/tools by description
{
name: 'search_skills',
description: 'Search for skills and tools you might need. Searches installed skills by content/name, and suggests built-in capabilities. Use when the user asks you to do something and you want to check if you have the right tool.',
parameters: {
type: 'object',
properties: {
query: { type: 'string', description: 'What capability are you looking for? (e.g., "generate PDF", "code review", "data analysis")' },
},
required: ['query'],
},
execute: async (args) => {
const query = (args.query as string).toLowerCase();
// Search installed skills
const skillFiles = fs.existsSync(skillsDir)
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'))
: [];
const matchingSkills = skillFiles
.map(f => {
const name = f.replace(/\.md$/, '');
const content = fs.readFileSync(path.join(skillsDir, f), 'utf-8');
const nameMatch = name.toLowerCase().includes(query);
const contentMatch = content.toLowerCase().includes(query);
return { name, content, match: nameMatch || contentMatch, nameMatch };
})
.filter(s => s.match)
.map(s => `- **${s.name}** (installed skill) — ${s.content.slice(0, 100)}...`);
// Built-in capability suggestions based on query keywords
const suggestions: string[] = [];
const builtins: Array<{ keywords: string[]; desc: string }> = [
{ keywords: ['document', 'docx', 'word', 'report'], desc: 'generate_docx — Create formatted Word documents from markdown' },
{ keywords: ['plan', 'planning', 'steps', 'strategy'], desc: 'create_plan — Create structured multi-step plans' },
{ keywords: ['git', 'commit', 'version', 'branch'], desc: 'git_status/git_diff/git_log/git_commit — Version control tools' },
{ keywords: ['memory', 'remember', 'recall', 'history'], desc: 'search_memory/save_memory — Persistent memory across sessions' },
{ keywords: ['web', 'search', 'internet', 'browse', 'fetch'], desc: 'web_search/web_fetch — Search and read web pages' },
{ keywords: ['file', 'read', 'write', 'edit', 'code'], desc: 'read_file/write_file/edit_file — File system operations' },
{ keywords: ['bash', 'command', 'terminal', 'shell', 'run'], desc: 'bash — Execute shell commands' },
{ keywords: ['knowledge', 'graph', 'entity', 'relation'], desc: 'query_knowledge/correct_knowledge — Knowledge graph operations' },
{ keywords: ['search', 'find', 'grep', 'pattern'], desc: 'search_files/search_content — Find files and search contents' },
];
for (const b of builtins) {
if (b.keywords.some(k => query.includes(k))) {
suggestions.push(`- ${b.desc} (built-in tool)`);
}
}
let output = '';
if (matchingSkills.length > 0) {
output += `## Matching Installed Skills\n${matchingSkills.join('\n')}\n\n`;
}
if (suggestions.length > 0) {
output += `## Relevant Built-in Tools\n${suggestions.join('\n')}\n\n`;
}
if (matchingSkills.length === 0 && suggestions.length === 0) {
output += `No installed skills or built-in tools match "${query}".\n\n`;
output += '**Suggestions:**\n';
output += '- Use `create_skill` to create a custom skill for this domain\n';
output += '- Use `web_search` to find instructions or templates online\n';
output += '- Use `bash` to check if relevant CLI tools are installed on the system\n';
}
return output;
},
},
// 6. suggest_skill — Context-aware skill recommendations
{
name: 'suggest_skill',
description: 'Get skill recommendations based on the current conversation context. Use this when you want to check if any installed skills could help with what the user is asking.',
parameters: {
type: 'object',
properties: {
context: { type: 'string', description: 'The current conversation topic or user request to match against installed skills' },
topN: { type: 'number', description: 'Maximum number of suggestions to return (default: 3)' },
},
required: ['context'],
},
execute: async (args) => {
const context = args.context as string;
const topN = (args.topN as number) ?? 3;
const recommender = new SkillRecommender({
getSkills: () => {
const files = fs.existsSync(skillsDir)
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'))
: [];
return files.map(f => ({
name: f.replace(/\.md$/, ''),
content: fs.readFileSync(path.join(skillsDir, f), 'utf-8').trim(),
}));
},
activeSkills: [],
});
const suggestions = recommender.recommend(context, topN);
if (suggestions.length === 0) {
return 'No matching skills found. Consider creating a custom skill with create_skill.';
}
return suggestions.map((s, i) =>
`${i + 1}. **${s.skillName}** (relevance: ${(s.relevanceScore * 100).toFixed(0)}%)\n ${s.reason}`,
).join('\n\n');
},
},
// 7. acquire_capability — Structured gap detection + candidate search
{
name: 'acquire_capability',
description: `Detect capability gaps and find installable skills to fill them. Use this when:
- You encounter a task you don't have a specialized skill for
- The user asks for something that could benefit from structured guidance (risk assessment, research synthesis, code review, etc.)
- You want to check if there's a curated skill available before attempting a task with general abilities
Returns a structured proposal showing what's already available, what can be installed, and a recommendation with reasoning. If a native tool or active skill already covers the need, it tells you so instead of proposing an install.`,
parameters: {
type: 'object',
properties: {
need: {
type: 'string',
description: 'What capability you need — describe the task or domain (e.g., "risk assessment for a project", "synthesize research from multiple sources", "code review checklist")',
},
},
required: ['need'],
},
execute: async (args) => {
const need = args.need as string;
if (!need || !need.trim()) {
return 'Error: "need" is required — describe what capability you are looking for.';
}
const installedSkills = deps.getInstalledSkills?.() ?? (() => {
const files = fs.existsSync(skillsDir)
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'))
: [];
return files.map(f => ({
name: f.replace(/\.md$/, ''),
content: fs.readFileSync(path.join(skillsDir, f), 'utf-8').trim(),
}));
})();
const starterDir = deps.starterSkillsDir ?? '';
const nativeTools = deps.nativeToolNames ?? [];
// Search marketplace if callback is available (non-blocking — graceful fallback)
let marketplaceCandidates: MarketplaceCandidate[] = [];
if (deps.searchMarketplace) {
try {
marketplaceCandidates = await deps.searchMarketplace(need);
} catch {
// Marketplace unavailable — continue with local sources only
}
}
const proposal = searchCapabilities({
need,
installedSkills,
starterSkillsDir: starterDir,
nativeToolNames: nativeTools,
marketplaceCandidates,
});
// Record proposal audit event if a gap was detected with a recommendation
if (proposal.gapDetected && proposal.recommendation?.trust) {
const trust = proposal.recommendation.trust;
deps.auditStore?.record({
capabilityName: proposal.recommendation.name,
capabilityType: proposal.recommendation.type,
source: proposal.recommendation.source,
riskLevel: trust.riskLevel,
trustSource: trust.trustSource,
approvalClass: trust.approvalClass,
action: 'proposed',
initiator: 'agent',
detail: `Proposed for need: ${need}`,
});
}
return proposal.summary;
},
},
// 8. install_capability — Install a specific capability from a curated source (requires approval)
{
name: 'install_capability',
description: `Install a capability identified by acquire_capability. This copies a curated starter skill into your active skill set. Requires user approval before installation (approval gate will appear in the UI).
After installation, the skill content is returned so you can immediately apply it to the current task. The skill is also hot-loaded into your system prompt for all future messages.
Only use this after acquire_capability has identified a specific installable candidate. Do not guess names — use the exact name and source from the proposal.`,
parameters: {
type: 'object',
properties: {
name: {
type: 'string',
description: 'Exact name of the capability to install (from acquire_capability proposal)',
},
source: {
type: 'string',
description: 'Source of the capability (e.g., "starter-pack"). Must match the source from the proposal.',
},
},
required: ['name', 'source'],
},
execute: async (args) => {
const name = args.name as string;
const source = args.source as string;
// Path traversal protection
if (name.includes('..') || name.includes('/') || name.includes('\\')) {
return 'Error: Invalid capability name.';
}
const starterDir = deps.starterSkillsDir ?? '';
const installedNames = new Set(
fs.existsSync(skillsDir)
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''))
: [],
);
// Validate this is a real, installable candidate
const validation = validateInstallCandidate(name, source, starterDir, installedNames);
if (!validation.valid) {
// Record failed install attempt
deps.auditStore?.record({
capabilityName: name,
capabilityType: 'skill',
source,
riskLevel: 'low',
trustSource: 'unknown',
approvalClass: 'standard',
action: 'failed',
initiator: 'agent',
detail: validation.error ?? 'Validation failed',
});
return `Error: ${validation.error}`;
}
// Read content from starter pack for trust assessment
const sourceContent = fs.readFileSync(validation.starterPath!, 'utf-8');
// ── SecurityGate scan (heuristics-only) ──────────────────────
let securityNote = '';
try {
const SGClass = await getSecurityGate();
const gate = new SGClass({
enable_gen_trust_hub: false,
enable_cisco_scanner: false,
enable_mcp_guardian: false,
enable_heuristics: true,
});
// Heuristics-only scan needs just these identity fields; the rest of
// MarketplacePackage is irrelevant here. Build a typed partial and
// widen to the full param type (scan() reads only name/type fields).
const scanPkg: Partial<MarketplacePackage> = {
name,
package_type: 'skill',
waggle_install_type: 'skill',
};
const scanResult = await gate.scan(scanPkg as MarketplacePackage, sourceContent);
// CRITICAL: refuse installation
if (scanResult.overall_severity === 'CRITICAL') {
deps.auditStore?.record({
capabilityName: name,
capabilityType: 'skill',
source,
riskLevel: 'critical',
trustSource: 'security-gate',
approvalClass: 'blocked',
action: 'blocked',
initiator: 'system',
detail: `SecurityGate blocked: ${scanResult.findings.length} CRITICAL finding(s)`,
});
const findingsText = scanResult.findings.map((f) => `- [${f.severity}] ${f.title}: ${f.description}`).join('\n');
return (
`## Installation Blocked — CRITICAL Security Finding\n\n` +
`**${name}** cannot be installed due to critical security issues:\n\n` +
`${findingsText}\n\n` +
`Security score: ${scanResult.security_score}/100\n\n` +
`This skill has been blocked for your protection. Do NOT attempt to bypass this gate.`
);
}
// HIGH: include warning note — the agent should inform the user
if (scanResult.overall_severity === 'HIGH') {
const findingsText = scanResult.findings.map((f) => `- [${f.severity}] ${f.title}`).join('\n');
securityNote = (
`\n### Security Warning\n` +
`SecurityGate found HIGH severity issues (score: ${scanResult.security_score}/100):\n` +
`${findingsText}\n` +
`The user should review these findings before relying on this skill.\n`
);
}
// MEDIUM: include informational note
if (scanResult.overall_severity === 'MEDIUM') {
securityNote = (
`\n### Security Note\n` +
`SecurityGate found minor issues (score: ${scanResult.security_score}/100, ${scanResult.findings.length} finding(s)). ` +
`Review recommended but not blocking.\n`
);
}
// LOW/CLEAN: include score in summary
if (scanResult.overall_severity === 'LOW' || scanResult.overall_severity === 'CLEAN') {
securityNote = `\n- **Security Score**: ${scanResult.security_score}/100 (${scanResult.overall_severity})\n`;
}
} catch {
// SecurityGate scan failure is non-blocking — proceed with install
securityNote = '\n- **Security Scan**: Unavailable (scan engine error)\n';
}
// Assess trust before installing
const trust = assessTrust({
capabilityType: 'skill',
source,
content: sourceContent,
});
// Record proposal audit event
deps.auditStore?.record({
capabilityName: name,
capabilityType: 'skill',
source,
riskLevel: trust.riskLevel,
trustSource: trust.trustSource,
approvalClass: trust.approvalClass,
action: 'approved',
initiator: 'agent',
detail: trust.explanation,
});
// Copy from starter pack to installed skills directory
const targetPath = path.join(skillsDir, `${name}.md`);
fs.copyFileSync(validation.starterPath!, targetPath);
// Trigger hot-reload so the skill is immediately available in runtime
onSkillsChanged?.();
// Record successful install audit event
deps.auditStore?.record({
capabilityName: name,
capabilityType: 'skill',
source,
riskLevel: trust.riskLevel,
trustSource: trust.trustSource,
approvalClass: trust.approvalClass,
action: 'installed',
initiator: 'agent',
detail: `Installed successfully. ${trust.explanation}`,
});
// Read the content to return it — so the agent can use it in the same turn
const content = fs.readFileSync(targetPath, 'utf-8');
const trustSummary = formatTrustSummary(trust);
return (
`## Skill Installed Successfully\n\n` +
`**${name}** has been installed from the ${source} and is now active.\n\n` +
`- **Location**: ${targetPath}\n` +
`- **Status**: Active — loaded into your system prompt\n` +
`- **Runtime**: Available immediately for this and all future sessions\n` +
securityNote + `\n` +
`### Trust Assessment\n${trustSummary}\n\n` +
`### Skill Content\n\nUse the following instructions to complete the current task:\n\n` +
`---\n\n${content}\n\n---\n\n` +
`You can now apply this skill to the user's request.`
);
},
},
// Skills 2.0 gap E: promote_skill — move a skill up one scope rung.
// personal → workspace. Enforces one-step-at-a-time.
{
name: 'promote_skill',
description:
'Promote an installed skill one scope up (personal → workspace). '
+ 'Team and enterprise scopes are not available in this edition. '
+ 'The file is moved to the appropriate directory and frontmatter is rewritten '
+ '(scope + promoted_from history).',
parameters: {
type: 'object',
properties: {
skill_name: {
type: 'string',
description: 'Name of the installed skill (SKILL.md filename without extension).',
},
target_scope: {
type: 'string',
enum: [...SKILL_SCOPE_ORDER],
description:
'Target scope. If omitted, auto-advances one step from the skill\'s current scope. '
+ 'Must be exactly one rung above the current scope — no jumps.',
},
},
required: ['skill_name'],
},
execute: async (args) => {
const skillName = args.skill_name as string;
const explicitTarget = args.target_scope as SkillScope | undefined;
// Resolve context for scope paths
const workspaceId = deps.getWorkspaceId?.() ?? null;
const teamId = deps.getTeamId?.() ?? null;
const ctx = { workspaceId, teamId };
// 1. Locate the skill: walk every scope dir the agent can see and
// find a SKILL file that matches the requested name. Preference
// order follows SKILL_SCOPE_ORDER so we pick the lowest scope
// available when multiple copies exist.
type Located = { scope: SkillScope; filePath: string; content: string };
let found: Located | null = null;
for (const s of SKILL_SCOPE_ORDER) {
const dir = getSkillDirForScope(waggleHome, s, ctx);
if (!dir || !fs.existsSync(dir)) continue;
const filePath = path.join(dir, `${skillName}.md`);
if (fs.existsSync(filePath)) {
found = {
scope: s,
filePath,
content: fs.readFileSync(filePath, 'utf-8'),
};
break;
}
}
if (!found) {
return `Skill "${skillName}" not found in any accessible scope. Use list_skills to see what's installed.`;
}
// 2. Read current scope from frontmatter (falling back to the
// dir-derived scope if the frontmatter is missing — handles
// pre-gap-E legacy skills).
const parsed = parseSkillFrontmatter(found.content);
const currentScope: SkillScope = parsed.frontmatter.scope ?? found.scope;
// 3. Determine target scope + validate one-step rule
const target = explicitTarget ?? nextScope(currentScope);
if (!target) {
return `Skill "${skillName}" is already at the top scope (${currentScope}). Cannot promote further.`;
}
const expectedNext = nextScope(currentScope);
if (target !== expectedNext) {
return (
`Invalid promotion: skill "${skillName}" is at scope "${currentScope}" and can only be promoted to "${expectedNext}". `
+ `Requested target "${target}" is not exactly one rung up. Multi-step promotions must be done one at a time.`
);
}
// 4. Context gating. Team and enterprise skill libraries belong to
// team mode, which this edition does not ship.
if (target === 'workspace' && !workspaceId) {
return `Cannot promote to workspace scope: no active workspace. Switch to a workspace first.`;
}
if (target === 'team' || target === 'enterprise') {
return `Cannot promote to ${target} scope: team and enterprise skill libraries are not available in this edition.`;
}
// 5. Resolve destination dir + path
const destDir = getSkillDirForScope(waggleHome, target, ctx);
if (!destDir) {
return `Cannot resolve destination directory for scope "${target}".`;
}
if (!fs.existsSync(destDir)) {
fs.mkdirSync(destDir, { recursive: true });
}
const destPath = path.join(destDir, `${skillName}.md`);
if (fs.existsSync(destPath)) {
return `Cannot promote: a skill named "${skillName}" already exists at scope "${target}". Rename one of them first.`;
}
// 6. Rewrite frontmatter: set new scope, append old to promoted_from
const updatedFrontmatter = {
...parsed.frontmatter,
scope: target,
promoted_from: [...(parsed.frontmatter.promoted_from ?? []), currentScope],
};
const newContent = redactSkillContent(serializeFrontmatter(updatedFrontmatter, parsed.body)).content;
// 7. Atomic-ish move: write to new location, then remove old.
// Writing first means a crash before the unlink leaves two copies,
// which is recoverable; a crash after the unlink but before the
// write would be catastrophic and is avoided by this ordering.
fs.writeFileSync(destPath, newContent, 'utf-8');
try {
fs.unlinkSync(found.filePath);
} catch {
// Non-fatal — leave a copy at the old location rather than
// failing the promotion. An audit warning is fine.
}
// 8. Let the agent reload its skill list so the new scope is picked up
onSkillsChanged?.();
return (
`## Skill Promoted\n\n`
+ `**${skillName}**: ${currentScope} → ${target}\n\n`
+ `- Moved from \`${found.filePath}\`\n`
+ `- Now at \`${destPath}\`\n`
+ `- Promotion history: ${updatedFrontmatter.promoted_from!.join(' → ')} → ${target}\n`
+ `\n`
+ `The skill is available immediately at the new scope. Agents in other `
+ `sessions will pick it up on their next skill reload.`
);
},
},
// Skills 2.0 gap A: auto_extract_skills — analyze the current session
// for a repeated workflow pattern and auto-create a personal-scope
// SKILL.md from it. Wires the previously-dormant
// detectWorkflowPattern → generateSkillMarkdown pipeline so the agent
// can learn from its own repetition without an explicit create_skill.
{
name: 'auto_extract_skills',
description:
'Scan the current session for repeated workflow patterns (the same 3+ tools '
+ 'used in the same order 2+ times) and auto-create a SKILL.md for any pattern '
+ 'found. Creates personal-scope skills only — promote_skill moves them up '
+ 'afterwards. Dedups by filename.',
parameters: {
type: 'object',
properties: {},
},
execute: async () => {
if (!deps.getSessionMessages) {
return 'auto_extract_skills is unavailable: session-message accessor not wired. (This is a local-only feature.)';
}
const messages = deps.getSessionMessages();
if (!messages || messages.length < 6) {
return `Not enough session history yet (${messages?.length ?? 0} messages). Need at least 6 to detect a pattern.`;
}
const result = await autoExtractAndCreateSkill(messages, {
personalSkillsDir: skillsDir,
});
if (result.filePath) {
onSkillsChanged?.();
return (
`## Skill Auto-Extracted\n\n`
+ `- Name: **${result.template!.name}**\n`
+ `- Category: ${result.template!.category}\n`
+ `- Tools: ${result.template!.tools.join(', ')}\n`
+ `- Written to: \`${result.filePath}\`\n`
+ `- Scope: personal (use promote_skill to move it up)\n`
);
}
if (result.reason === 'already_exists') {
return `Pattern "${result.template!.name}" detected, but a skill with that filename already exists. Skipped.`;
}
return 'No repeatable workflow pattern detected in this session yet. Keep using the tools — the pattern needs at least 2 repetitions.';
},
},
// Skills 2.0 gap F: retire_skills — archive personal-scope skills
// that haven't been used in N days. Keeps the skill library from
// growing monotonically. Runs in dry-run by default so the agent can
// report the plan before any file moves.
{
name: 'retire_skills',
description:
'Archive personal-scope skills that have not been used within the idle window. '
+ 'Moves stale SKILL.md files to ~/.waggle/skills-archive/ (recoverable — no deletion). '
+ 'Default max_idle_days is 90. Default dry_run is true — call with dry_run: false to '
+ 'actually move the files.',
parameters: {
type: 'object',
properties: {
max_idle_days: {
type: 'number',
description: 'Skills not used within this many days are retired. Default 90.',
},
dry_run: {
type: 'boolean',
description: 'When true (default), reports the plan without moving files.',
},
},
},
execute: async (args) => {
const maxIdleDays = typeof args.max_idle_days === 'number' ? args.max_idle_days : 90;
const dryRun = args.dry_run !== false; // default true
const report = retireStaleSkills(waggleHome, {
maxIdleDays,
dryRun,
});
if (!dryRun && report.retired.length > 0) {
onSkillsChanged?.();
}
const lines: string[] = [
`## Skill Retirement ${dryRun ? '(dry run)' : ''}`,
'',
`- Scanned: ${report.scanned}`,
`- Retired: ${report.retired.length}${report.retired.length > 0 ? ` — ${report.retired.join(', ')}` : ''}`,
`- Skipped fresh: ${report.skipped.filter(s => s.reason === 'fresh').length}`,
];
const errors = report.skipped.filter(s => s.reason !== 'fresh');
if (errors.length > 0) {
lines.push(`- Errors: ${errors.map(e => `${e.name}: ${e.reason}`).join('; ')}`);
}
if (dryRun && report.retired.length > 0) {
lines.push('', `Run again with \`dry_run: false\` to move ${report.retired.length} file${report.retired.length > 1 ? 's' : ''} to the archive.`);
}
if (!dryRun && report.archived.length > 0) {
lines.push('', `Archive dir: \`${report.archived[0].replace(/\\[^\\]+$/, '')}\``);
}
return lines.join('\n');
},
},
];
}