@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/cli/commands/skills.js

@@ -2,20 +2,23 @@ import fs from 'fs';
 import path from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
-import { promises as fsPromises } from 'node:fs';
-import { loadOfficialSkills } from '../../skills/official-skills.js';
+import { loadBuiltinSkills } from '../../skills/builtin-skills.js';
 import { SkillRegistry } from '../../skills/registry.js';
 import { skillInvoke } from '../../skills/tools/skill-invoke.js';
 import { skillList } from '../../skills/tools/skill-list.js';
-import { pullCandidates, matchToOfficial, evaluateWithAI, generateReport, applyDecisions, DEFAULT_SOURCES, } from '../../skills/upgrade-engine.js';
-import { ConfigManager } from '../../core/config.js';
-import { ClaudeProvider } from '../../core/ai/provider.js';
+import { SQLiteStorage } from '../../core/storage/sqlite.js';
 import { FORGE_PATHS } from '../../core/constants.js';
+import { resolveSessionId } from '../utils/resolve-session.js';
 const SKILLS_DIR = path.join(homedir(), '.claude', 'skills');
 function resolveBuiltinDir() {
+    // Built-in skills live under `src/skills/distilled/`.
     const thisFile = fileURLToPath(import.meta.url);
-    return path.join(path.dirname(thisFile), '../../skills/official');
+    return path.join(path.dirname(thisFile), '../../skills/distilled');
 }
+// Sentinel session id used when no real session can be resolved (e.g. a bare
+// CLI call outside any Claude session). Keeps the skill_invocations row writable
+// (session_id is NOT NULL) while flagging it as session-less for analytics.
+const CLI_SESSION_FALLBACK = 'cli-no-session';
 /**
  * List skills with optional keyword filter and JSON output.
  * Delegates to the shared skillList() tool so CLI and Agent share one code path.
@@ -37,11 +40,11 @@ async function listSkills(options) {
         console.log('No skills found.');
         return;
     }
-    // Human-readable output. Include `isOfficial` hint via registry lookup.
+    // Human-readable output. Include `isBuiltin` hint via registry lookup.
     console.log(`Available skills (${result.total}):\n`);
     for (const s of result.skills) {
         const full = registry.get(s.id);
-        const type = full?.isOfficial ? 'official' : 'user';
+        const type = full?.isBuiltin ? 'built-in' : 'user';
         console.log(`- ${s.id} [${type}]`);
         console.log(`  name: ${s.name}`);
         if (s.description) {
@@ -56,144 +59,397 @@ async function listSkills(options) {
 /**
  * Invoke a skill by id, printing its full methodology content.
  * Exit code 1 on failure so Bash callers can detect errors.
+ *
+ * Telemetry (decision 4e118b92): every successful CLI invoke now persists a
+ * skill_invocations row via the SHARED skillInvoke() write path, marked
+ * invocation_type='cli' so it is distinguishable from MCP (`dynamic`) and
+ * legacy keyword-match (`static`) rows. The `--reason` is recorded verbatim so
+ * follow-through SQL like `reason LIKE 'coder/%'` / `'verify/%'` works, and
+ * parseWorkflowMeta (inside skillInvoke) populates workflow/phase/feature_slug.
+ *
+ * This is the working path for subagents, which have NO MCP access — the MCP
+ * `skill_invoke` tool is uncallable from coder/verify-agent, so guidance now
+ * points them at `cf skill invoke` (Bash).
  */
-async function invokeSkill(skillId, options) {
+export async function invokeSkill(skillId, options, deps = {}) {
     const registry = new SkillRegistry();
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const error = deps.io?.error ?? ((m) => console.error(m));
+    // Open storage for telemetry. Own it only if we created it (don't close an
+    // injected one — the caller owns its lifecycle).
+    const ownStorage = !deps.storage;
+    let storage;
     try {
-        const result = await skillInvoke({ skill_id: skillId, reason: options.reason }, { skillRegistry: registry });
+        storage = deps.storage ?? new SQLiteStorage(FORGE_PATHS.database());
+    }
+    catch {
+        // Telemetry must never break the primary "print methodology" behavior.
+        // If the DB can't be opened, fall through with storage=undefined.
+        storage = undefined;
+    }
+    // Resolve the session id (flag → $CLAUDE_SESSION_ID env → DB lookup), then
+    // fall back to a sentinel so the row still records (session_id is NOT NULL).
+    let sessionId = options.sessionId ?? '';
+    if (storage && !sessionId) {
+        try {
+            const resolved = resolveSessionId(storage, {
+                sessionId: options.sessionId,
+                projectPath: options.project ?? process.cwd(),
+            });
+            sessionId = resolved.sessionId;
+        }
+        catch {
+            sessionId = '';
+        }
+    }
+    if (!sessionId)
+        sessionId = CLI_SESSION_FALLBACK;
+    try {
+        const result = await skillInvoke({ skill_id: skillId, reason: options.reason }, {
+            skillRegistry: registry,
+            // Telemetry context: storage + sessionId together trigger the
+            // skill_invocations write inside skillInvoke. invocationType='cli'
+            // is the source marker.
+            storage,
+            sessionId,
+            invocationType: 'cli',
+            // decision 234f1ad4 Q6: write agent_id when the caller passes --agent, so
+            // the (agent,skill) pairing can graduate from reason-prefix proxy key to a
+            // first-class key. Omitted → NULL (unchanged legacy behavior).
+            agentId: options.agent,
+            // decision 39839e30 Part 2: stamp the project so the workplace "Skill 调用"
+            // KPI can filter by project. Same source as the session DB lookup above.
+            projectPath: options.project ?? process.cwd(),
+        });
         if (options.json) {
-            console.log(JSON.stringify(result, null, 2));
+            log(JSON.stringify(result, null, 2));
             return;
         }
-        console.log(`# ${result.skill_name}`);
+        log(`# ${result.skill_name}`);
         if (result.keywords.length > 0) {
-            console.log(`\n> keywords: ${result.keywords.join(', ')}`);
+            log(`\n> keywords: ${result.keywords.join(', ')}`);
         }
-        console.log();
-        console.log(result.content);
+        log('');
+        log(result.content);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        console.error(`Error: ${msg}`);
+        error(`Error: ${msg}`);
         process.exit(1);
     }
+    finally {
+        if (ownStorage && storage) {
+            try {
+                storage.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
 }
+// Skill usefulness feedback (decision d24cd3a2 P0,
+// spec docs/design/2026-06-11/1524-skill-usefulness-feedback-spec.md).
+const USEFULNESS_RATINGS = ['helped', 'partial', 'not-actionable'];
 /**
- * Coordinate the full skill upgrade pipeline.
- * Default: dry-run — generates a report without writing to src/.
- * --apply: read report and apply decisions.
- * --rollback <ts>: restore official skills from a backup timestamp.
+ * `cf skill feedback --skill <id> --rating <helped|partial|not-actionable>`:
+ * stamp a POST-USE usefulness self-assessment onto the most-recent un-rated
+ * skill_invocations row for that skill in the current session.
+ *
+ * Telemetry discipline: this is advisory — it must NEVER throw into the agent's
+ * main flow. Invalid rating → exit 1 (the one hard validation, so a typo is
+ * caught). DB-open failure / 0-row-found → soft path, exit 0.
  */
-async function upgradeSkills(options) {
-    const reportPath = options.report ?? FORGE_PATHS.skillUpgradeReport();
-    const officialDir = resolveBuiltinDir();
-    const backupBaseDir = FORGE_PATHS.backups('skills');
-    const candidatesDir = FORGE_PATHS.skillCandidates();
-    // ── Rollback mode ────────────────────────────────────────────────────────
-    if (options.rollback) {
-        const backupPath = path.join(backupBaseDir, options.rollback);
-        try {
-            await fsPromises.access(backupPath);
+export async function feedbackSkill(options, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const error = deps.io?.error ?? ((m) => console.error(m));
+    const skillId = options.skill?.trim();
+    if (!skillId) {
+        error('Error: --skill <skill_id> is required');
+        process.exit(1);
+        return;
+    }
+    const rating = options.rating?.trim();
+    if (!rating || !USEFULNESS_RATINGS.includes(rating)) {
+        error(`Error: --rating must be one of ${USEFULNESS_RATINGS.join(' | ')} (got: ${rating ?? '<none>'})`);
+        process.exit(1);
+        return;
+    }
+    const ownStorage = !deps.storage;
+    let storage;
+    try {
+        storage = deps.storage ?? new SQLiteStorage(FORGE_PATHS.database());
+    }
+    catch {
+        // Fail-soft: never break the agent's flow over a missing DB.
+        error('Warning: could not open storage; usefulness feedback skipped');
+        return;
+    }
+    try {
+        // Resolve session the same way invokeSkill does, then fall back to the
+        // sentinel so a session-less call still targets that skill's recent pulls.
+        let sessionId = options.sessionId ?? '';
+        if (!sessionId) {
+            try {
+                const resolved = resolveSessionId(storage, {
+                    sessionId: options.sessionId,
+                    projectPath: options.project ?? process.cwd(),
+                });
+                sessionId = resolved.sessionId;
+            }
+            catch {
+                sessionId = '';
+            }
         }
-        catch {
-            console.error(`Backup not found: ${backupPath}`);
-            process.exit(1);
+        if (!sessionId)
+            sessionId = CLI_SESSION_FALLBACK;
+        const stamped = storage.writeSkillUsefulness({
+            session_id: sessionId,
+            skill_id: skillId,
+            usefulness: rating,
+            note: options.note ?? null,
+        });
+        if (stamped > 0) {
+            log(`recorded usefulness=${rating} for ${skillId} (${stamped} row stamped)`);
         }
-        const files = await fsPromises.readdir(backupPath);
-        for (const file of files) {
-            if (!file.endsWith('.md'))
-                continue;
-            await fsPromises.copyFile(path.join(backupPath, file), path.join(officialDir, file));
+        else {
+            // Soft warning — do NOT fail the agent's flow over a missing pull row.
+            log(`no un-rated pull found for ${skillId} in session ${sessionId} (nothing stamped)`);
         }
-        console.log(`Rolled back ${files.filter(f => f.endsWith('.md')).length} files from ${backupPath}`);
-        console.log('Run `npm run build` to rebuild with restored skills.');
+    }
+    catch (err) {
+        // Telemetry must never throw into the agent's main path.
+        const msg = err instanceof Error ? err.message : String(err);
+        error(`Warning: usefulness feedback failed: ${msg}`);
+    }
+    finally {
+        if (ownStorage && storage) {
+            try {
+                storage.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/**
+ * `cf skill usefulness [--json]`: per-skill usefulness aggregation, sorted
+ * worst-actionable-rate first (least-useful skills on top = P1 refinement
+ * candidates). actionable_rate = helped / total_rated (STRICT helped-only).
+ * Un-rated pulls are reported as `pending`, excluded from the rate denominator.
+ */
+export async function usefulnessSkills(options, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const error = deps.io?.error ?? ((m) => console.error(m));
+    const ownStorage = !deps.storage;
+    let storage;
+    try {
+        storage = deps.storage ?? new SQLiteStorage(FORGE_PATHS.database());
+    }
+    catch {
+        error('Error: could not open storage');
+        process.exit(1);
         return;
     }
-    // ── Apply mode ───────────────────────────────────────────────────────────
-    if (options.apply) {
-        try {
-            await fsPromises.access(reportPath);
+    try {
+        const rows = storage.aggregateSkillUsefulness({});
+        if (options.json) {
+            log(JSON.stringify(rows, null, 2));
+            return;
         }
-        catch {
-            console.error(`Report not found: ${reportPath}`);
-            console.error('Run `cf skills upgrade` first to generate a report.');
-            process.exit(1);
+        if (rows.length === 0) {
+            log('No skill invocations recorded yet.');
+            return;
+        }
+        log('Skill usefulness (worst actionable-rate first):\n');
+        log('skill_id'.padEnd(44) + 'rate'.padStart(7) + 'rated'.padStart(7) +
+            'help'.padStart(6) + 'part'.padStart(6) + 'n/a'.padStart(6) + 'pend'.padStart(6));
+        for (const r of rows) {
+            const rate = r.total_rated > 0 ? `${(r.actionable_rate * 100).toFixed(0)}%` : '-';
+            log(r.skill_id.padEnd(44) +
+                rate.padStart(7) +
+                String(r.total_rated).padStart(7) +
+                String(r.helped).padStart(6) +
+                String(r.partial).padStart(6) +
+                String(r.not_actionable).padStart(6) +
+                String(r.pending).padStart(6));
         }
-        console.log(`Applying decisions from ${reportPath}...`);
-        const result = await applyDecisions(reportPath, officialDir, backupBaseDir);
-        console.log(`\nApply complete:`);
-        console.log(`  Applied : ${result.applied}`);
-        console.log(`  Skipped : ${result.skipped}`);
-        console.log(`  Backup  : ${result.backupPath}`);
-        console.log('\nNext steps:');
-        console.log('  1. npm run build              # rebuild dist with new skill content');
-        console.log('  2. git add src/skills/official/');
-        console.log('  3. git commit -m "chore: upgrade official skills (cf skills upgrade --apply)"');
-        console.log(`\nIf unsatisfied, rollback with: cf skills upgrade --rollback ${path.basename(result.backupPath)}`);
-        return;
     }
-    // ── Dry-run (report generation) mode ────────────────────────────────────
-    console.log('Fetching candidate skills...');
-    const candidates = await pullCandidates(DEFAULT_SOURCES, candidatesDir);
-    console.log(`  Found ${candidates.length} candidate skills`);
-    const officialSkills = loadOfficialSkills(officialDir);
-    console.log(`  Loaded ${officialSkills.length} official skills`);
-    // Set up AI provider
-    const config = new ConfigManager().get();
-    if (!config.ai.api_key) {
-        console.error('No AI API key configured. Run `cf menu` to set it up.');
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        error(`Error: ${msg}`);
         process.exit(1);
     }
-    const aiProvider = new ClaudeProvider(config.ai.api_key, config.ai.model, config.ai.base_url);
-    let matched = 0;
-    let unmatched = 0;
-    const entries = [];
-    console.log('\nEvaluating candidates...');
-    for (const candidate of candidates) {
-        const matchResult = matchToOfficial(candidate, officialSkills);
-        if (!matchResult) {
-            unmatched++;
-            continue;
+    finally {
+        if (ownStorage && storage) {
+            try {
+                storage.close();
+            }
+            catch { /* ignore */ }
         }
-        matched++;
-        const official = officialSkills.find((o) => o.name === matchResult.officialId);
-        if (!official)
-            continue;
-        process.stdout.write(`  ${candidate.id} → ${official.name} (score ${matchResult.score})... `);
-        const decision = await evaluateWithAI(candidate, official, aiProvider);
-        const action = decision.needs_review
-            ? 'needs_review'
-            : decision.action;
-        process.stdout.write(`${action}\n`);
-        entries.push({
-            officialId: official.name,
-            candidateId: candidate.id,
-            candidateSource: candidate.source,
-            action,
-            confidence: decision.confidence,
-            reasoning: decision.reasoning,
-            candidateFilePath: candidate.filePath,
-            merged_content: decision.merged_content,
-        });
     }
-    const stats = { total: candidates.length, matched, unmatched };
-    await generateReport(entries, reportPath, stats);
-    console.log(`\nReport generated: ${reportPath}`);
-    console.log(`Summary: ${matched} matched, ${unmatched} unmatched (of ${candidates.length} total)`);
-    console.log('\nReview the report, then run:');
-    console.log('  cf skills upgrade --apply   (to apply decisions)');
+}
+// ---------------------------------------------------------------------------
+// `cf skill search <task-desc>` — dynamic skill discovery (decision c20c2d1f, C1)
+//
+// Replaces the static per-agent trigger tables ("situation → hardcoded skill_id")
+// with a lexical, deterministic search: an agent describes the sub-task it is
+// ACTUALLY doing and gets back relevance-ranked skill candidates. Ranking is
+// pure token-overlap (skill name + description + keywords vs the task tokens) —
+// NO LLM, NO embedding (fast, deterministic, zero spend). The LLM picks 0-1 from
+// the candidates afterwards.
+//
+// Anti-noise (decision d08da374): when the top score is below SEARCH_MIN_SCORE
+// we explicitly report "no strong match — suggest skip pull" so the agent skips
+// rather than pulling a weak candidate (the "pull everything every time" trap).
+// ---------------------------------------------------------------------------
+/** Default number of ranked candidates returned. */
+const SEARCH_DEFAULT_TOP = 5;
+/**
+ * Minimum top score for the result set to count as a "strong match". Below this,
+ * `searchSkills` flags `no_strong_match: true` so the agent skips the pull.
+ * Scoring is token-overlap (see scoreSkillMatch): a curated KEYWORD hit scores 2,
+ * a single name/description word scores 1. The threshold of 2 means a real match
+ * needs either one curated-keyword hit OR two distinct text-word overlaps — a
+ * lone generic word (e.g. "branch", "guidelines") never qualifies as strong.
+ * This is the anti-noise guard (decision d08da374): weak single-word coincidences
+ * are surfaced only as "weak candidates", and the agent is told to skip.
+ */
+const SEARCH_MIN_SCORE = 2;
+/**
+ * Tokenize a free-text string into lowercase alphanumeric tokens.
+ * Splits on any non-alphanumeric boundary; keeps CJK runs intact (CJK chars are
+ * not \w, so a CJK phrase becomes one token — keyword frontmatter stores CJK
+ * phrases like "接口设计" whole, so whole-token equality still matches).
+ */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9一-鿿]+/u)
+        .filter(t => t.length > 0);
+}
+/**
+ * Score one skill against the query tokens by token overlap.
+ *
+ * - Each query token that appears among the skill's keyword tokens scores 2
+ *   (keywords are the curated relevance signal → weighted highest).
+ * - Each query token that appears in the skill's name/description tokens scores 1.
+ * - A query token counts at most once (keyword hit dominates a name/desc hit).
+ *
+ * Pure + deterministic — no LLM, no embedding. Exported-shape via searchSkills.
+ */
+export function scoreSkillMatch(skill, queryTokens) {
+    const keywordTokens = new Set();
+    for (const kw of skill.keywords) {
+        for (const t of tokenize(kw))
+            keywordTokens.add(t);
+    }
+    const textTokens = new Set([
+        ...tokenize(skill.name),
+        ...tokenize(skill.description ?? ''),
+        // skill ids are hyphenated (distilled-api-design) → tokenize for partial hits
+        ...tokenize(skill.id),
+    ]);
+    let score = 0;
+    const seen = new Set();
+    for (const qt of queryTokens) {
+        if (seen.has(qt))
+            continue; // dedupe repeated query tokens
+        seen.add(qt);
+        if (keywordTokens.has(qt)) {
+            score += 2;
+        }
+        else if (textTokens.has(qt)) {
+            score += 1;
+        }
+    }
+    return score;
+}
+/**
+ * Rank skills by relevance to a task description. Pure function over a skill
+ * list so it is unit-testable without a registry/filesystem.
+ */
+export function rankSkills(skills, taskDesc, top) {
+    const queryTokens = tokenize(taskDesc);
+    const scored = skills
+        .map(s => ({
+        id: s.id,
+        name: s.name,
+        description: s.description ?? '',
+        keywords: s.keywords,
+        score: scoreSkillMatch(s, queryTokens),
+    }))
+        .filter(m => m.score > 0)
+        // Highest score first; tie-break alphabetically for deterministic output.
+        .sort((a, b) => (b.score - a.score) || a.id.localeCompare(b.id))
+        .slice(0, Math.max(1, top));
+    const bestScore = scored.length > 0 ? scored[0].score : 0;
+    return {
+        query: taskDesc,
+        matches: scored,
+        no_strong_match: bestScore < SEARCH_MIN_SCORE,
+    };
+}
+/**
+ * `cf skill search <task-desc> [--top N] [--json]`: dynamic skill discovery.
+ * Source of truth is the live SkillRegistry (same data `cf skill list` uses) —
+ * no new data source. Supports machine (--json, for agents) + human output.
+ */
+export async function searchSkills(taskDesc, options, deps = {}) {
+    const log = deps.io?.log ?? ((m) => console.log(m));
+    const error = deps.io?.error ?? ((m) => console.error(m));
+    const query = (taskDesc ?? '').trim();
+    if (!query) {
+        error('Error: a task description is required, e.g. cf skill search "add SSE reconnect to streaming endpoint"');
+        process.exit(1);
+        return;
+    }
+    let top = SEARCH_DEFAULT_TOP;
+    if (options.top !== undefined) {
+        const parsed = Number.parseInt(options.top, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            top = parsed;
+    }
+    const registry = deps.registry ?? new SkillRegistry();
+    const skills = registry.getAll().map(s => ({
+        id: s.id,
+        name: s.name,
+        description: s.description,
+        keywords: s.keywords,
+    }));
+    const result = rankSkills(skills, query, top);
+    if (options.json) {
+        log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // Human-readable output.
+    if (result.matches.length === 0 || result.no_strong_match) {
+        log(`No strong skill match for: "${query}"`);
+        log('Suggestion: skip the skill pull (note `skill-pull-skipped: no-match`).');
+        if (result.matches.length > 0) {
+            log('\nWeak candidates (below match threshold, NOT recommended):');
+            for (const m of result.matches) {
+                log(`  - ${m.id} (score ${m.score})`);
+            }
+        }
+        return;
+    }
+    log(`Top skill matches for: "${query}"\n`);
+    for (const m of result.matches) {
+        log(`- ${m.id} (score ${m.score})`);
+        if (m.description)
+            log(`  ${m.description}`);
+    }
+    log('\nPick at most 1 (the most relevant); if none truly fits, skip the pull.');
 }
 function registerSkillSubcommands(skills) {
     skills
         .command('sync')
-        .description('Write official skills to ~/.claude/skills/')
+        .description('Write built-in skills to ~/.claude/skills/')
         .option('-f, --force', 'Overwrite existing files regardless of version')
         .action((options) => {
         syncSkills(options);
     });
     skills
         .command('list')
-        .description('List all skills (official + user) with optional keyword filter')
+        .description('List all skills (built-in + user) with optional keyword filter')
         .option('--keywords <keywords>', 'Comma-separated keywords to filter by')
         .option('--json', 'Output as JSON (machine-readable)')
         .action(async (options) => {
@@ -202,32 +458,62 @@ function registerSkillSubcommands(skills) {
     skills
         .command('invoke <skill_id>')
         .description('Invoke a skill and print its full methodology content')
-        .option('--reason <reason>', 'Reason for invoking (used for audit log)')
+        .option('--reason <reason>', 'Reason for invoking (used for audit log; use "coder/<phase>" / "verify/<phase>" prefix for follow-through telemetry)')
+        .option('--session-id <id>', 'Session id for the audit row (defaults to $CLAUDE_SESSION_ID env → DB lookup)')
+        .option('--project <path>', 'Project path for session DB lookup (defaults to cwd)')
+        .option('--agent <name>', 'Agent name to stamp on the row (writes agent_id; decision 234f1ad4 Q6)')
         .option('--json', 'Output as JSON (machine-readable)')
         .action(async (skillId, options) => {
         await invokeSkill(skillId, options);
     });
+    // Dynamic skill discovery (decision c20c2d1f, C1). Agents describe the
+    // sub-task they are ACTUALLY doing → get relevance-ranked candidates; the LLM
+    // picks 0-1. Replaces the static per-agent trigger tables. Deterministic
+    // token-overlap ranking — no LLM, no embedding.
+    skills
+        .command('search <task-desc>')
+        .description('Rank skills by relevance to a task description (dynamic discovery; agents pick 0-1)')
+        .option('--top <n>', `Max candidates to return (default ${SEARCH_DEFAULT_TOP})`)
+        .option('--json', 'Output as JSON (machine-readable; for agent parsing)')
+        .action(async (taskDesc, options) => {
+        await searchSkills(taskDesc, options);
+    });
+    // Skill usefulness feedback (decision d24cd3a2 P0). After an agent USES a
+    // pulled skill it rates how actionable the CONTENT was on THIS project's task.
+    skills
+        .command('feedback')
+        .description('Record post-use usefulness for a pulled skill (helped|partial|not-actionable)')
+        .option('--skill <skill_id>', 'Skill id that was pulled (required)')
+        .option('--rating <rating>', 'helped | partial | not-actionable (required)')
+        .option('--note <text>', 'One line: what was / was not applicable to THIS project task')
+        .option('--session-id <id>', 'Session id (defaults to $CLAUDE_SESSION_ID env → DB lookup)')
+        .option('--project <path>', 'Project path for session DB lookup (defaults to cwd)')
+        .action(async (options) => {
+        await feedbackSkill(options);
+    });
     skills
-        .command('upgrade')
-        .description('AI-assisted upgrade of official skills (dry-run by default)')
-        .option('--apply', 'Apply decisions from the last report')
-        .option('--rollback <timestamp>', 'Rollback to a backup (e.g. 20260518-1930)')
-        .option('--report <path>', 'Custom report path')
+        .command('usefulness')
+        .description('Per-skill usefulness aggregation (actionable_rate = helped/total, worst-first)')
+        .option('--json', 'Output as JSON (machine-readable; P1 refinement input)')
         .action(async (options) => {
-        await upgradeSkills(options);
+        await usefulnessSkills(options);
     });
+    // NOTE: `cf skills distill ...` was REMOVED in R-A (spec 1851). Distillation
+    // is now Web-UI-only and shells out to the `claude` CLI (R-B). The earlier
+    // CLI entry points (init / run / review / refresh) are intentionally gone —
+    // do not re-add them without a separate spec.
 }
 export function register(program) {
     // Primary command: `cf skills ...`
     const skills = program
         .command('skills')
-        .description('Manage official and user skills (list | invoke | sync | upgrade)');
+        .description('Manage built-in and user skills (list | invoke | sync)');
     registerSkillSubcommands(skills);
     // Singular alias: `cf skill ...` — preferred for Agent Bash calls where
     // `cf skill invoke <id>` reads more naturally than the plural form.
     const skill = program
         .command('skill')
-        .description('Alias of `skills` (list | invoke | sync | upgrade)');
+        .description('Alias of `skills` (list | invoke | sync)');
     registerSkillSubcommands(skill);
 }
 function syncSkills(options) {
@@ -237,7 +523,7 @@ function syncSkills(options) {
     let added = 0;
     let skipped = 0;
     let updated = 0;
-    const officialSkills = loadOfficialSkills(resolveBuiltinDir());
+    const officialSkills = loadBuiltinSkills(resolveBuiltinDir());
     for (const skill of officialSkills) {
         const filePath = path.join(SKILLS_DIR, `${skill.name}.md`);
         const exists = fs.existsSync(filePath);