@trawlme/cli 1.7.0 → 1.8.0

package/README.md

@@ -56,6 +56,21 @@ trawl scraps account clear-session <id>
 trawl scraps account status <id> [--json]
 ```
 
+### Claude Code skills
+
+The CLI bundles a Claude Code skill that teaches Claude how to use `trawl`. Once installed, Claude can manage scraps for you via prompts.
+
+```
+trawl skills list                            List bundled skills and install status
+trawl skills install [<skill>] [--local]     Install all (or one). Default: ~/.claude/skills/
+trawl skills uninstall [<skill>] [--local]   Remove
+trawl skills update [<skill>] [--local]      Reinstall (force sync with CLI version)
+```
+
+Skills auto-update silently when you upgrade the CLI — no need to re-install manually.
+
+You can also install skills standalone (without the CLI): `npx @trawlme/skills install`.
+
 ## Environment variables
 
 | Variable      | Description                                          |

package/dist/commands/skills.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const skills: Command;

package/dist/commands/skills.js

@@ -0,0 +1,83 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { listBundledSkills, installSkill, uninstallSkill, getBundledSkillsVersion, getInstalledVersion, isSkillInstalled, } from '../lib/skills.js';
+function pickScope(opts) {
+    return opts.local ? 'local' : 'user';
+}
+function pickSkills(arg) {
+    const all = listBundledSkills();
+    if (!arg || arg === 'all')
+        return all;
+    if (!all.includes(arg)) {
+        throw new Error(`Unknown skill "${arg}". Available: ${all.join(', ') || '(none)'}`);
+    }
+    return [arg];
+}
+export const skills = new Command('skills').description('Manage Claude Code skills bundled with the Trawl CLI');
+skills
+    .command('list')
+    .description('List bundled skills and their installed status')
+    .action(() => {
+    const bundled = listBundledSkills();
+    if (!bundled.length) {
+        console.log(chalk.dim('No bundled skills.'));
+        return;
+    }
+    const version = getBundledSkillsVersion();
+    console.log(chalk.dim(`@trawlme/skills@${version}\n`));
+    for (const name of bundled) {
+        const userInstalled = isSkillInstalled(name, 'user');
+        const localInstalled = isSkillInstalled(name, 'local');
+        const installedVersion = getInstalledVersion(name, 'user') ?? getInstalledVersion(name, 'local');
+        const stale = installedVersion && installedVersion !== version;
+        const tag = userInstalled
+            ? localInstalled
+                ? '(user + local)'
+                : '(user)'
+            : localInstalled
+                ? '(local)'
+                : '(not installed)';
+        const staleNote = stale ? chalk.yellow(` outdated: ${installedVersion} → ${version}`) : '';
+        console.log(`  ${name} ${chalk.dim(tag)}${staleNote}`);
+    }
+});
+skills
+    .command('install [skill]')
+    .description('Install one or all bundled skills')
+    .option('--local', 'Install at project level (./.claude/skills) instead of user level (~/.claude/skills)')
+    .action((skill, opts) => {
+    const scope = pickScope(opts);
+    const targets = pickSkills(skill);
+    for (const name of targets) {
+        const dest = installSkill(name, scope);
+        console.log(chalk.green(`✓ Installed "${name}"`) + chalk.dim(` at ${dest}`));
+    }
+    console.log(chalk.dim('  Restart Claude Code if it was already running.'));
+});
+skills
+    .command('uninstall [skill]')
+    .description('Remove one or all bundled skills')
+    .option('--local', 'Remove from project level (./.claude/skills)')
+    .action((skill, opts) => {
+    const scope = pickScope(opts);
+    const targets = pickSkills(skill);
+    for (const name of targets) {
+        const dest = uninstallSkill(name, scope);
+        if (dest)
+            console.log(chalk.green(`✓ Removed "${name}"`) + chalk.dim(` from ${dest}`));
+        else
+            console.log(chalk.dim(`  No "${name}" found`));
+    }
+});
+skills
+    .command('update [skill]')
+    .description('Reinstall over the existing skill (force sync with CLI version)')
+    .option('--local', 'Update at project level')
+    .action((skill, opts) => {
+    const scope = pickScope(opts);
+    const targets = pickSkills(skill);
+    for (const name of targets) {
+        const dest = installSkill(name, scope);
+        console.log(chalk.green(`✓ Updated "${name}"`) + chalk.dim(` at ${dest}`));
+    }
+});

package/dist/index.js

@@ -3,6 +3,9 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { login, logout } from './commands/login.js';
 import { scraps } from './commands/scraps.js';
+import { skills } from './commands/skills.js';
+import { autoUpdateInstalledSkills } from './lib/skills.js';
+autoUpdateInstalledSkills();
 const program = new Command()
     .name('trawl')
     .description('Trawl CLI — manage scraps from the terminal')
@@ -11,6 +14,7 @@ const program = new Command()
 program.addCommand(login);
 program.addCommand(logout);
 program.addCommand(scraps);
+program.addCommand(skills);
 program.parseAsync().catch((err) => {
     const { debug } = program.opts();
     if (debug || process.env['DEBUG']) {

package/dist/lib/skills.d.ts

@@ -0,0 +1,12 @@
+export declare function getBundledSkillsVersion(): string;
+export declare function listBundledSkills(): string[];
+export declare function installSkill(name: string, scope: 'user' | 'local'): string;
+export declare function uninstallSkill(name: string, scope: 'user' | 'local'): string | null;
+export declare function getInstalledVersion(name: string, scope: 'user' | 'local'): string | null;
+export declare function isSkillInstalled(name: string, scope: 'user' | 'local'): boolean;
+/**
+ * Silently re-installs any skill whose installed version doesn't match the bundled one.
+ * Called on CLI startup to keep skills in sync with the CLI version.
+ * Never throws — failures are silent so they don't break unrelated commands.
+ */
+export declare function autoUpdateInstalledSkills(): void;

package/dist/lib/skills.js

@@ -0,0 +1,77 @@
+import { mkdirSync, existsSync, rmSync, readFileSync, writeFileSync, readdirSync, statSync, cpSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+function getSkillsPackageRoot() {
+    const pkgJson = require.resolve('@trawlme/skills/package.json');
+    return dirname(pkgJson);
+}
+export function getBundledSkillsVersion() {
+    const pkg = JSON.parse(readFileSync(join(getSkillsPackageRoot(), 'package.json'), 'utf8'));
+    return pkg.version;
+}
+export function listBundledSkills() {
+    const src = join(getSkillsPackageRoot(), 'skills');
+    if (!existsSync(src))
+        return [];
+    return readdirSync(src).filter((name) => {
+        const dir = join(src, name);
+        return statSync(dir).isDirectory() && existsSync(join(dir, 'SKILL.md'));
+    });
+}
+function getSkillsBase(scope) {
+    const base = scope === 'local' ? join(process.cwd(), '.claude') : join(homedir(), '.claude');
+    return join(base, 'skills');
+}
+export function installSkill(name, scope) {
+    const src = join(getSkillsPackageRoot(), 'skills', name);
+    if (!existsSync(src)) {
+        throw new Error(`Skill "${name}" not found in @trawlme/skills`);
+    }
+    const dest = join(getSkillsBase(scope), name);
+    if (existsSync(dest))
+        rmSync(dest, { recursive: true, force: true });
+    mkdirSync(dest, { recursive: true });
+    cpSync(src, dest, { recursive: true });
+    writeFileSync(join(dest, '.version'), getBundledSkillsVersion(), 'utf8');
+    return dest;
+}
+export function uninstallSkill(name, scope) {
+    const dest = join(getSkillsBase(scope), name);
+    if (!existsSync(dest))
+        return null;
+    rmSync(dest, { recursive: true, force: true });
+    return dest;
+}
+export function getInstalledVersion(name, scope) {
+    const versionFile = join(getSkillsBase(scope), name, '.version');
+    if (!existsSync(versionFile))
+        return null;
+    return readFileSync(versionFile, 'utf8').trim();
+}
+export function isSkillInstalled(name, scope) {
+    return existsSync(join(getSkillsBase(scope), name));
+}
+/**
+ * Silently re-installs any skill whose installed version doesn't match the bundled one.
+ * Called on CLI startup to keep skills in sync with the CLI version.
+ * Never throws — failures are silent so they don't break unrelated commands.
+ */
+export function autoUpdateInstalledSkills() {
+    try {
+        const bundledVersion = getBundledSkillsVersion();
+        for (const name of listBundledSkills()) {
+            for (const scope of ['user', 'local']) {
+                if (!isSkillInstalled(name, scope))
+                    continue;
+                if (getInstalledVersion(name, scope) === bundledVersion)
+                    continue;
+                installSkill(name, scope);
+            }
+        }
+    }
+    catch {
+        // Silent: skill auto-update should never block the CLI
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trawlme/cli",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Trawl CLI — manage scraps from the terminal",
   "type": "module",
   "bin": {
@@ -40,6 +40,7 @@
     "url": "https://github.com/comes-io/trawl_cli/issues"
   },
   "dependencies": {
+    "@trawlme/skills": "^1.0.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "conf": "^15.1.0",