@npeercy/skills 0.1.0

package/bin/skills.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import {
+  cmdInit, cmdLogin, cmdLogout, cmdSearch, cmdInfo,
+  cmdInstall, cmdList, cmdUpdate, cmdUninstall,
+  cmdEdit, cmdValidate, cmdPublish, cmdImport, cmdDoctor,
+  cmdShare, cmdUnshare, cmdVisibility,
+} from '../lib/skills.js';
+
+const USAGE = `skill-sharer — CLI skill manager for coding agents
+
+Usage: skills <command> [options]
+
+Setup:
+  init [--server <url>] [--token <token>] [--no-import]   Setup skill-sharer
+  login [--server <url>] [--token <token>]               Set/refresh token (prompts if missing)
+  logout                                                  Remove stored token
+
+Discovery:
+  search [query]                        Search skills (no query = browse all)
+  info <skill>                          Skill details + versions
+
+Install:
+  install <skill>[@ver] [--agent <a>] [--dry-run]
+  list [--verify] [--outdated] [--json]
+  update [<skill>]                      Update one or all
+  uninstall <skill>
+
+Import:
+  import [<path>]                       Import unmanaged skills
+
+Authoring:
+  edit <skill>                          Print canonical path
+  validate <path>                       Check SKILL.md
+  publish [<path>] [--message <msg>]    Publish to server
+
+Sharing:
+  share <skill> --with <user> [--maintain]
+  unshare <skill> --from <user>
+  visibility <skill> [private|org|public]
+
+Maintenance:
+  doctor [--dry]                        Diagnose + fix issues
+`;
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    console.log(USAGE);
+    return;
+  }
+
+  const cmd = args[0];
+  const rest = args.slice(1);
+
+  try {
+    switch (cmd) {
+      case 'init': {
+        const { values } = parseArgs({ args: rest, options: {
+          server: { type: 'string' },
+          token: { type: 'string' },
+          'no-import': { type: 'boolean', default: false },
+        }, allowPositionals: false });
+        await cmdInit({ server: values.server, token: values.token, noImport: values['no-import'] });
+        break;
+      }
+      case 'login': {
+        const { values } = parseArgs({ args: rest, options: {
+          server: { type: 'string' },
+          token: { type: 'string' },
+        }, allowPositionals: false });
+        await cmdLogin({ server: values.server, token: values.token });
+        break;
+      }
+      case 'logout':
+        await cmdLogout();
+        break;
+      case 'search': {
+        const { positionals } = parseArgs({ args: rest, allowPositionals: true, options: {} });
+        await cmdSearch({ query: positionals[0] || '' });
+        break;
+      }
+      case 'info': {
+        const { positionals } = parseArgs({ args: rest, allowPositionals: true, options: {} });
+        if (!positionals[0]) throw new Error('Usage: skills info <skill>');
+        await cmdInfo({ skill: positionals[0] });
+        break;
+      }
+      case 'install': {
+        const { values, positionals } = parseArgs({ args: rest, options: {
+          agent: { type: 'string' },
+          'dry-run': { type: 'boolean', default: false },
+        }, allowPositionals: true });
+        if (!positionals[0]) throw new Error('Usage: skills install <skill>[@version]');
+        await cmdInstall({ skill: positionals[0], agent: values.agent, dryRun: values['dry-run'] });
+        break;
+      }
+      case 'list': {
+        const { values } = parseArgs({ args: rest, options: {
+          verify: { type: 'boolean', default: false },
+          outdated: { type: 'boolean', default: false },
+          json: { type: 'boolean', default: false },
+        }, allowPositionals: false });
+        await cmdList(values);
+        break;
+      }
+      case 'update': {
+        const { positionals } = parseArgs({ args: rest, allowPositionals: true, options: {} });
+        await cmdUpdate({ skill: positionals[0] });
+        break;
+      }
+      case 'uninstall': {
+        const { positionals } = parseArgs({ args: rest, allowPositionals: true, options: {} });
+        if (!positionals[0]) throw new Error('Usage: skills uninstall <skill>');
+        await cmdUninstall({ skill: positionals[0] });
+        break;
+      }
+      case 'import': {
+        const { positionals } = parseArgs({ args: rest, allowPositionals: true, options: {} });
+        await cmdImport({ path: positionals[0], all: true });
+        break;
+      }
+      case 'edit': {
+        const { positionals } = parseArgs({ args: rest, allowPositionals: true, options: {} });
+        if (!positionals[0]) throw new Error('Usage: skills edit <skill>');
+        await cmdEdit({ skill: positionals[0] });
+        break;
+      }
+      case 'validate': {
+        const { positionals } = parseArgs({ args: rest, allowPositionals: true, options: {} });
+        if (!positionals[0]) throw new Error('Usage: skills validate <path>');
+        await cmdValidate({ path: positionals[0] });
+        break;
+      }
+      case 'publish': {
+        const { values, positionals } = parseArgs({ args: rest, options: {
+          message: { type: 'string', short: 'm' },
+        }, allowPositionals: true });
+        await cmdPublish({ path: positionals[0], message: values.message });
+        break;
+      }
+      case 'share': {
+        const { values, positionals } = parseArgs({ args: rest, options: {
+          with: { type: 'string' },
+          maintain: { type: 'boolean', default: false },
+        }, allowPositionals: true });
+        if (!positionals[0] || !values.with) throw new Error('Usage: skills share <skill> --with <user>');
+        await cmdShare({ skill: positionals[0], with: values.with, maintain: values.maintain });
+        break;
+      }
+      case 'unshare': {
+        const { values, positionals } = parseArgs({ args: rest, options: {
+          from: { type: 'string' },
+        }, allowPositionals: true });
+        if (!positionals[0] || !values.from) throw new Error('Usage: skills unshare <skill> --from <user>');
+        await cmdUnshare({ skill: positionals[0], from: values.from });
+        break;
+      }
+      case 'visibility': {
+        const { positionals } = parseArgs({ args: rest, allowPositionals: true, options: {} });
+        if (!positionals[0]) throw new Error('Usage: skills visibility <skill> [private|org|public]');
+        await cmdVisibility({ skill: positionals[0], value: positionals[1] });
+        break;
+      }
+      case 'doctor': {
+        const { values } = parseArgs({ args: rest, options: {
+          dry: { type: 'boolean', default: false },
+        }, allowPositionals: false });
+        await cmdDoctor({ dry: values.dry });
+        break;
+      }
+      default:
+        console.error(`Unknown command: ${cmd}`);
+        console.log(USAGE);
+        process.exit(1);
+    }
+  } catch (e) {
+    console.error(`error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/builtin-skills/creating-or-updating-a-new-skill/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: creating-or-updating-a-new-skill
+description: Use when creating a new skill, editing an existing skill's SKILL.md, or publishing changes to the skill-sharer server.
+---
+
+# Creating or updating a skill
+
+## SKILL.md structure
+
+Every skill needs a `SKILL.md` file with frontmatter:
+
+```yaml
+---
+name: my-skill-name
+description: When this skill should be activated by the agent
+---
+
+# Title
+
+Instructions, examples, and decision logic in markdown.
+```
+
+- `name`: lowercase letters, digits, hyphens only
+- `description`: tells the agent WHEN to use this skill (this is how agents decide to activate it)
+
+## Creating a new skill
+
+1. Create a directory with a `SKILL.md`:
+   ```bash
+   mkdir my-skill
+   # Write the SKILL.md with frontmatter + instructions
+   ```
+
+2. Validate:
+   ```bash
+   skills validate ./my-skill
+   ```
+
+3. Publish:
+   ```bash
+   skills publish ./my-skill --message "Initial version"
+   ```
+   The server assigns `v1` automatically. Org and user are inferred from your login.
+
+4. Install locally:
+   ```bash
+   skills install my-skill
+   ```
+
+## Editing an existing skill
+
+1. Get the canonical path:
+   ```bash
+   skills edit <skill>
+   # Prints: ~/.local/share/skill-sharer/skills/org/user/name/vN/SKILL.md
+   ```
+
+2. Read and edit the SKILL.md at that path using normal file tools.
+
+3. Validate:
+   ```bash
+   skills validate <path-to-skill-dir>
+   ```
+
+4. Publish the update:
+   ```bash
+   skills publish --message "Description of changes"
+   ```
+   No path or flags needed — infers from the last edited managed skill.
+
+**Decision logic:**
+- Always validate before publishing.
+- The edit is live locally immediately (symlinks point to managed store).
+- Publishing pushes to the server so others can install the new version.
+- If the skill isn't installed locally yet, install it after publishing.
+
+## Sharing
+
+```bash
+# Make a skill visible to all org members (default)
+skills visibility <skill> org
+
+# Make public (anyone can install, no auth needed)
+skills visibility <skill> public
+
+# Grant access to a specific user on a private skill
+skills share <skill> --with <username>
+```

package/builtin-skills/skill-sharer-help/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: skill-sharer-help
+description: Use when the user asks to install, update, search, list, import, or manage coding agent skills via skill-sharer.
+---
+
+# skill-sharer help
+
+skill-sharer manages skills across coding agents (Claude Code, Pi, etc.).
+Skills are installed as symlinks from a managed store into each agent's skill directory.
+
+## Finding and installing skills
+
+Use short names — the CLI resolves them automatically when unambiguous.
+
+```bash
+# Search for a skill
+skills search <query>
+
+# Get details (versions, description)
+skills info <skill>
+
+# Install (latest version, to all agents)
+skills install <skill>
+
+# Install a specific version
+skills install <skill>@v2
+
+# Install to one agent only
+skills install <skill> --agent pi
+```
+
+**Decision logic:**
+- Always search first to find the full `org/user/name`.
+- If search returns multiple matches, show them and ask the user which one.
+- If the user says "install X", search for X, then install the match.
+
+## Checking installed skills
+
+```bash
+# List all installed skills
+skills list
+
+# Check health (symlinks, checksums)
+skills list --verify
+
+# Show only outdated skills
+skills list --outdated
+```
+
+## Updating and removing
+
+```bash
+# Update all skills to latest
+skills update
+
+# Update one skill
+skills update <skill>
+
+# Remove a skill
+skills uninstall <skill>
+```
+
+## Importing existing skills
+
+If the user has skills already in `~/.claude/skills/` or `~/.pi/agent/skills/` that aren't managed by skill-sharer:
+
+```bash
+# Scan all agent dirs and import unmanaged skills
+skills import
+```
+
+**Decision logic:**
+- Use `skills doctor` to check for unmanaged skills.
+- Use `skills import` to bring them under management.
+- Import moves the original, creates namespaced symlinks, and publishes to the server.
+
+## Maintenance
+
+```bash
+# Diagnose and fix broken symlinks, report unmanaged skills
+skills doctor
+
+# Diagnose only (no fixes)
+skills doctor --dry
+```

package/lib/api.js

@@ -0,0 +1,78 @@
+import { loadConfig } from './config.js';
+
+function headers(token) {
+  const h = { 'Content-Type': 'application/json' };
+  if (token) h['Authorization'] = `Bearer ${token}`;
+  return h;
+}
+
+async function request(method, path, body = null) {
+  const cfg = loadConfig();
+  if (!cfg.server) throw new Error('No server configured. Run: skills init --server <url>');
+
+  const url = `${cfg.server.replace(/\/$/, '')}${path}`;
+  const opts = { method, headers: headers(cfg.token) };
+  if (body) opts.body = JSON.stringify(body);
+
+  const res = await fetch(url, opts);
+  const data = await res.json().catch(() => ({}));
+
+  if (!res.ok) {
+    const msg = data.error || `HTTP ${res.status}`;
+    const err = new Error(msg);
+    err.status = res.status;
+    throw err;
+  }
+  return data;
+}
+
+// --- Auth ---
+export async function createToken(user) {
+  return request('POST', '/auth/token', { user });
+}
+
+export async function whoami() {
+  return request('GET', '/auth/me');
+}
+
+export async function logout() {
+  return request('DELETE', '/auth/token');
+}
+
+// --- Skills ---
+export async function browse(query) {
+  const q = query ? `?q=${encodeURIComponent(query)}` : '';
+  return request('GET', `/skills${q}`);
+}
+
+export async function info(org, user, name) {
+  return request('GET', `/skills/${org}/${user}/${name}`);
+}
+
+export async function download(org, user, name, version) {
+  return request('GET', `/skills/${org}/${user}/${name}/@${version}`);
+}
+
+export async function publish(org, user, name, message, files) {
+  return request('POST', '/skills', { org, user, name, message, files });
+}
+
+export async function setVisibility(org, user, name, visibility) {
+  return request('PATCH', `/skills/${org}/${user}/${name}/visibility`, { visibility });
+}
+
+export async function getAcl(org, user, name) {
+  return request('GET', `/skills/${org}/${user}/${name}/acl`);
+}
+
+export async function grantAccess(org, user, name, grantUser, role) {
+  return request('POST', `/skills/${org}/${user}/${name}/acl`, { user: grantUser, role });
+}
+
+export async function revokeAccess(org, user, name, grantUser) {
+  return request('DELETE', `/skills/${org}/${user}/${name}/acl/${grantUser}`);
+}
+
+export async function deleteSkill(org, user, name) {
+  return request('DELETE', `/skills/${org}/${user}/${name}`);
+}

package/lib/config.js

@@ -0,0 +1,96 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// --- Paths ---
+const CONFIG_HOME = process.env.SKILLS_CONFIG_HOME || join(homedir(), '.config', 'skill-sharer');
+const DATA_HOME = process.env.SKILLS_DATA_HOME || join(homedir(), '.local', 'share', 'skill-sharer');
+
+export const configDir = () => CONFIG_HOME;
+export const dataDir = () => DATA_HOME;
+export const configPath = () => join(CONFIG_HOME, 'config.json');
+export const statePath = () => join(DATA_HOME, 'state.json');
+export const skillsDir = () => join(DATA_HOME, 'skills');
+
+// --- JSON helpers ---
+function loadJson(path, fallback) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function saveJson(path, data) {
+  mkdirSync(join(path, '..'), { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+
+// --- Config ---
+const DEFAULT_CONFIG = { server: 'https://skills.npeercy.com', org: '', token: '' };
+
+export function loadConfig() {
+  mkdirSync(CONFIG_HOME, { recursive: true });
+  const cfg = { ...DEFAULT_CONFIG, ...loadJson(configPath(), {}) };
+  return cfg;
+}
+
+export function saveConfig(cfg) {
+  saveJson(configPath(), cfg);
+}
+
+// --- State ---
+const DEFAULT_STATE = { installed: {} };
+
+export function loadState() {
+  mkdirSync(DATA_HOME, { recursive: true });
+  mkdirSync(skillsDir(), { recursive: true });
+  const st = { ...DEFAULT_STATE, ...loadJson(statePath(), {}) };
+  st.installed = st.installed || {};
+  return st;
+}
+
+export function saveState(st) {
+  saveJson(statePath(), st);
+}
+
+// --- Agents ---
+const KNOWN_AGENTS = {
+  'claude-code': join(homedir(), '.claude', 'skills'),
+  'pi': join(homedir(), '.pi', 'agent', 'skills'),
+};
+
+export function detectAgents() {
+  const found = {};
+  for (const [name, path] of Object.entries(KNOWN_AGENTS)) {
+    if (existsSync(path)) found[name] = path;
+  }
+  return found;
+}
+
+// --- Skill ID helpers ---
+export function parseSkillId(input, config) {
+  const parts = input.replace(/@.*$/, '').split('/').filter(Boolean);
+  if (parts.length === 3) return parts.join('/');
+  if (parts.length === 2) {
+    if (!config.org) throw new Error('No org configured. Run: skills init --server <url>');
+    return `${config.org}/${parts.join('/')}`;
+  }
+  if (parts.length === 1) return null; // needs resolution via search
+  throw new Error('Invalid skill identifier');
+}
+
+export function parseVersion(input) {
+  const m = input.match(/@(.+)$/);
+  return m ? m[1] : null;
+}
+
+export function splitSkillId(id) {
+  const [org, user, name] = id.split('/');
+  return { org, user, name };
+}
+
+export function symlinkName(skillId) {
+  return skillId.replace(/\//g, '--');
+}
+
+export function managedPath(skillId, version) {
+  const { org, user, name } = splitSkillId(skillId);
+  return join(skillsDir(), org, user, name, version);
+}

package/lib/skills.js

@@ -0,0 +1,725 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, symlinkSync, unlinkSync, rmSync, lstatSync, readlinkSync } from 'fs';
+import { join, resolve, relative, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createHash } from 'crypto';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import {
+  loadConfig, saveConfig, loadState, saveState,
+  detectAgents, parseSkillId, parseVersion, splitSkillId,
+  symlinkName, managedPath,
+} from './config.js';
+import * as api from './api.js';
+
+// --- Frontmatter parser ---
+export function parseFrontmatter(content) {
+  const lines = content.split('\n');
+  if (lines[0].trim() !== '---') return null;
+  const meta = {};
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') break;
+    const m = lines[i].match(/^(\w[\w-]*)\s*:\s*(.+)$/);
+    if (m) meta[m[1]] = m[2].replace(/^["']|["']$/g, '');
+  }
+  return (meta.name && meta.description) ? meta : null;
+}
+
+// --- Collect files from directory ---
+function collectFiles(dir) {
+  const result = {};
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      if (entry.name.startsWith('.')) continue;
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else result[relative(dir, full)] = readFileSync(full, 'utf8');
+    }
+  }
+  walk(dir);
+  return result;
+}
+
+// --- Checksum ---
+function fileHash(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+function computeChecksums(dir) {
+  const out = {};
+  function walk(d) {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else out[relative(dir, full)] = fileHash(full);
+    }
+  }
+  if (existsSync(dir)) walk(dir);
+  return out;
+}
+
+// --- Short name resolution ---
+async function resolveSkillId(input, config) {
+  const exact = parseSkillId(input, config);
+  if (exact) return exact; // 3-part or 2-part resolved
+
+  // 1-part: search the index
+  const results = await api.browse(input);
+  const matches = results.filter(s =>
+    s.name === input || s.id.endsWith('/' + input)
+  );
+  if (matches.length === 1) return matches[0].id;
+  if (matches.length === 0) throw new Error(`No skill found matching "${input}"`);
+  throw new Error(
+    `Ambiguous: "${input}" matches multiple skills:\n` +
+    matches.map(m => `  ${m.id}`).join('\n') +
+    '\nUse the full org/user/name to be specific.'
+  );
+}
+
+function linkNameForSkill(skillId) {
+  if (skillId.startsWith('__builtin__/local/')) {
+    return `builtin--${splitSkillId(skillId).name}`;
+  }
+  return symlinkName(skillId);
+}
+
+async function promptForToken(serverUrl) {
+  console.log(`No token configured for ${serverUrl}.`);
+  console.log('1) Open: https://skills.npeercy.com');
+  console.log('2) Click Sign in');
+  console.log('3) Copy the auto-filled login command/token');
+  const rl = createInterface({ input, output });
+  const token = (await rl.question('Paste token: ')).trim();
+  rl.close();
+  if (!token) throw new Error('Token is required.');
+  return token;
+}
+
+async function installBuiltins(agents) {
+  const st = loadState();
+  const builtinsRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'builtin-skills');
+  if (!existsSync(builtinsRoot)) return;
+
+  const installed = [];
+  for (const entry of readdirSync(builtinsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const srcDir = join(builtinsRoot, entry.name);
+    const skillMd = join(srcDir, 'SKILL.md');
+    if (!existsSync(skillMd)) continue;
+
+    const meta = parseFrontmatter(readFileSync(skillMd, 'utf8'));
+    if (!meta) continue;
+
+    const id = `__builtin__/local/${meta.name}`;
+    const version = 'v1';
+    const dest = managedPath(id, version);
+    const files = collectFiles(srcDir);
+
+    // Write to managed store
+    rmSync(dest, { recursive: true, force: true });
+    mkdirSync(dest, { recursive: true });
+    for (const [filePath, content] of Object.entries(files)) {
+      const full = join(dest, filePath);
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, content);
+    }
+
+    // Symlink into all detected agents
+    const linkName = linkNameForSkill(id);
+    for (const agentPath of Object.values(agents)) {
+      mkdirSync(agentPath, { recursive: true });
+      const link = join(agentPath, linkName);
+      try {
+        const st = lstatSync(link);
+        if (st.isDirectory()) rmSync(link, { recursive: true, force: true });
+        else unlinkSync(link);
+      } catch {
+        // doesn't exist
+      }
+      symlinkSync(dest, link);
+    }
+
+    st.installed[id] = {
+      version,
+      installed_at: new Date().toISOString(),
+      path: dest,
+      agents: Object.keys(agents).sort(),
+      checksums: computeChecksums(dest),
+      builtin: true,
+    };
+
+    installed.push(meta.name);
+  }
+
+  saveState(st);
+  if (installed.length > 0) {
+    console.log('\nInstalled built-in skills:');
+    for (const name of installed) {
+      console.log(`  ✓ ${name} → ${Object.keys(agents).join(', ') || '(no agents detected)'}`);
+    }
+  }
+}
+
+// --- Commands ---
+
+export async function cmdInit(args) {
+  const cfg = loadConfig();
+
+  // Server
+  if (args.server) {
+    cfg.server = args.server.replace(/\/$/, '');
+  }
+  if (!cfg.server) {
+    cfg.server = 'https://skills.npeercy.com';
+  }
+
+  // Detect agents
+  const agents = detectAgents();
+  console.log('Scanning for coding agents...');
+  for (const [name, path] of Object.entries(agents)) {
+    console.log(`✓ ${name.padEnd(12)} ${path}`);
+  }
+  if (Object.keys(agents).length === 0) {
+    console.log('  (no agents detected)');
+  }
+
+  // Login
+  if (args.token) {
+    cfg.token = args.token;
+    saveConfig(cfg);
+  }
+  if (!cfg.token) {
+    cfg.token = await promptForToken(cfg.server);
+    saveConfig(cfg);
+  }
+
+  // Verify token
+  saveConfig(cfg);
+  try {
+    const me = await api.whoami();
+    cfg.org = me.org;
+    saveConfig(cfg);
+    console.log(`\n✓ Logged in as ${me.user} (org: ${me.org}, role: ${me.role})`);
+  } catch (e) {
+    throw new Error(`Token invalid: ${e.message}`);
+  }
+
+  // Import existing skills
+  if (!args.noImport) {
+    await cmdImport({ all: true, quiet: true });
+  }
+
+  // Install built-ins
+  await installBuiltins(agents);
+
+  console.log('\nReady! Ask your agent to "install a skill" or "create a new skill".');
+}
+
+export async function cmdLogin(args) {
+  const cfg = loadConfig();
+  if (args.server) {
+    cfg.server = args.server.replace(/\/$/, '');
+  }
+  if (!cfg.server) cfg.server = 'https://skills.npeercy.com';
+
+  if (args.token) {
+    cfg.token = args.token;
+  } else if (!cfg.token) {
+    cfg.token = await promptForToken(cfg.server);
+  }
+
+  saveConfig(cfg);
+  const me = await api.whoami();
+  cfg.org = me.org;
+  saveConfig(cfg);
+  console.log(`✓ Logged in as ${me.user} (org: ${me.org}, role: ${me.role})`);
+}
+
+export async function cmdLogout() {
+  const cfg = loadConfig();
+  if (cfg.token) {
+    try { await api.logout(); } catch { /* ignore */ }
+  }
+  cfg.token = '';
+  saveConfig(cfg);
+  console.log('Logged out.');
+}
+
+export async function cmdSearch(args) {
+  const results = await api.browse(args.query || '');
+  if (results.length === 0) {
+    console.log(args.query ? `No results for "${args.query}"` : 'No skills found.');
+    return;
+  }
+  console.log('SKILL'.padEnd(56) + 'VERSION'.padEnd(10) + 'VISIBILITY'.padEnd(12) + 'DESCRIPTION');
+  for (const s of results) {
+    console.log(
+      s.id.padEnd(56) +
+      (s.latest_version || '-').padEnd(10) +
+      (s.visibility || 'org').padEnd(12) +
+      (s.description || '').slice(0, 60)
+    );
+  }
+}
+
+export async function cmdInfo(args) {
+  const cfg = loadConfig();
+  const id = await resolveSkillId(args.skill, cfg);
+  const { org, user, name } = splitSkillId(id);
+  const data = await api.info(org, user, name);
+
+  const st = loadState();
+  const installed = st.installed[id];
+
+  console.log(`Skill:       ${data.id}`);
+  console.log(`Visibility:  ${data.visibility}`);
+  console.log(`Description: ${data.description || ''}`);
+  console.log('');
+  console.log('Versions:');
+  for (const v of (data.versions || []).reverse()) {
+    const mark = installed && installed.version === v ? ' ← installed' : '';
+    console.log(`  ${v}${mark}`);
+  }
+}
+
+export async function cmdInstall(args) {
+  const cfg = loadConfig();
+  const agents = detectAgents();
+  const st = loadState();
+
+  const rawSkill = args.skill.replace(/@.*$/, '');
+  const version = parseVersion(args.skill) || 'latest';
+  const id = await resolveSkillId(rawSkill, cfg);
+  const { org, user, name } = splitSkillId(id);
+
+  const targetAgents = args.agent ? { [args.agent]: agents[args.agent] } : agents;
+  if (args.agent && !agents[args.agent]) {
+    throw new Error(`Unknown agent: ${args.agent}`);
+  }
+  if (Object.keys(targetAgents).length === 0) throw new Error('No agents detected.');
+
+  const data = await api.download(org, user, name, version);
+  const ver = data.version;
+  const dest = managedPath(id, ver);
+  const linkName = linkNameForSkill(id);
+
+  console.log(`Installing ${id}@${ver}`);
+  for (const [agentName, agentPath] of Object.entries(targetAgents)) {
+    console.log(`  -> ${agentName}: ${join(agentPath, linkName)}`);
+  }
+
+  if (args.dryRun) {
+    console.log('Dry run — no changes written.');
+    return;
+  }
+
+  // Write files to managed store
+  mkdirSync(dest, { recursive: true });
+  for (const [filePath, content] of Object.entries(data.files)) {
+    const full = join(dest, filePath);
+    mkdirSync(join(full, '..'), { recursive: true });
+    writeFileSync(full, content);
+  }
+
+  // Create symlinks
+  for (const [agentName, agentPath] of Object.entries(targetAgents)) {
+    mkdirSync(agentPath, { recursive: true });
+    const link = join(agentPath, linkName);
+    try { unlinkSync(link); } catch { /* ok if doesn't exist */ }
+    symlinkSync(dest, link);
+  }
+
+  // Update state
+  st.installed[id] = {
+    version: ver,
+    installed_at: new Date().toISOString(),
+    path: dest,
+    agents: Object.keys(targetAgents).sort(),
+    checksums: computeChecksums(dest),
+  };
+  saveState(st);
+  console.log('Installed.');
+}
+
+export async function cmdList(args) {
+  const cfg = loadConfig();
+  const st = loadState();
+  const agents = detectAgents();
+
+  const rows = [];
+  for (const [id, rec] of Object.entries(st.installed).sort()) {
+    let status = 'ok';
+    if (args.verify) {
+      status = verifyInstall(id, rec, agents);
+    }
+
+    let latest = rec.version;
+    if (args.outdated || args.verify) {
+      try {
+        const { org, user, name } = splitSkillId(id);
+        const data = await api.info(org, user, name);
+        latest = data.latest_version || rec.version;
+      } catch { /* offline */ }
+    }
+
+    const outdated = latest !== rec.version;
+    if (args.outdated && !outdated) continue;
+    if (outdated && status === 'ok') status = 'outdated';
+
+    rows.push({ id, version: rec.version, latest, agents: rec.agents.join(','), status });
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+
+  if (rows.length === 0) {
+    console.log('No installed skills.');
+    return;
+  }
+
+  console.log('SKILL'.padEnd(56) + 'INSTALLED'.padEnd(10) + 'LATEST'.padEnd(10) + 'AGENTS'.padEnd(20) + 'STATUS');
+  for (const r of rows) {
+    console.log(r.id.padEnd(56) + r.version.padEnd(10) + r.latest.padEnd(10) + r.agents.padEnd(20) + r.status);
+  }
+}
+
+function verifyInstall(id, rec, agents) {
+  const dest = rec.path;
+  if (!existsSync(dest)) return 'missing';
+
+  const linkName = linkNameForSkill(id);
+  for (const agentName of rec.agents) {
+    const agentPath = agents[agentName];
+    if (!agentPath) return 'missing-agent';
+    const link = join(agentPath, linkName);
+    try {
+      if (!lstatSync(link).isSymbolicLink()) return 'not-symlink';
+      if (resolve(readlinkSync(link)) !== resolve(dest)) return 'broken-link';
+    } catch {
+      return 'broken-link';
+    }
+  }
+
+  const expected = rec.checksums || {};
+  const actual = computeChecksums(dest);
+  if (JSON.stringify(expected) !== JSON.stringify(actual)) return 'modified';
+
+  return 'ok';
+}
+
+export async function cmdUpdate(args) {
+  const cfg = loadConfig();
+  const st = loadState();
+
+  const targets = args.skill
+    ? [await resolveSkillId(args.skill, cfg)]
+    : Object.keys(st.installed);
+
+  let updated = 0;
+  for (const id of targets) {
+    const rec = st.installed[id];
+    if (!rec) continue;
+    const { org, user, name } = splitSkillId(id);
+    try {
+      const data = await api.info(org, user, name);
+      if (data.latest_version === rec.version) continue;
+      await cmdInstall({ skill: `${id}@${data.latest_version}`, dryRun: false });
+      updated++;
+    } catch (e) {
+      console.error(`  ${id}: ${e.message}`);
+    }
+  }
+  console.log(`Updated ${updated} skill(s).`);
+}
+
+export async function cmdUninstall(args) {
+  const cfg = loadConfig();
+  const st = loadState();
+  const id = await resolveSkillId(args.skill, cfg);
+  const rec = st.installed[id];
+  if (!rec) { console.log('Not installed.'); return; }
+
+  const agents = detectAgents();
+  const linkName = linkNameForSkill(id);
+  for (const agentName of rec.agents) {
+    const agentPath = agents[agentName];
+    if (!agentPath) continue;
+    const link = join(agentPath, linkName);
+    try {
+      const st = lstatSync(link);
+      if (st.isDirectory()) rmSync(link, { recursive: true, force: true });
+      else unlinkSync(link);
+    } catch { /* ok */ }
+  }
+
+  if (rec.path && existsSync(rec.path)) {
+    rmSync(rec.path, { recursive: true, force: true });
+  }
+
+  delete st.installed[id];
+  saveState(st);
+  console.log(`Uninstalled ${id}.`);
+}
+
+export async function cmdEdit(args) {
+  const cfg = loadConfig();
+  const st = loadState();
+  const id = await resolveSkillId(args.skill, cfg);
+  const rec = st.installed[id];
+  if (!rec) throw new Error(`${id} is not installed.`);
+  console.log(join(rec.path, 'SKILL.md'));
+}
+
+export async function cmdValidate(args) {
+  const dir = resolve(args.path);
+  const skillMd = join(dir, 'SKILL.md');
+  if (!existsSync(skillMd)) throw new Error('SKILL.md not found');
+  const content = readFileSync(skillMd, 'utf8');
+  const meta = parseFrontmatter(content);
+  if (!meta) throw new Error('Invalid frontmatter — needs name and description');
+
+  if (!/^[a-z0-9-]+$/.test(meta.name)) {
+    throw new Error('Skill name must be lowercase letters, digits, and hyphens only');
+  }
+
+  console.log('✓ SKILL.md found');
+  console.log('✓ frontmatter valid');
+  console.log(`✓ name: ${meta.name}`);
+  console.log('Ready to publish.');
+}
+
+export async function cmdPublish(args) {
+  const cfg = loadConfig();
+  const st = loadState();
+
+  let dir, skillOrg, skillUser, skillName;
+
+  if (args.path) {
+    dir = resolve(args.path);
+  } else {
+    // Find last edited managed skill
+    const entries = Object.entries(st.installed).sort((a, b) =>
+      (b[1].installed_at || '').localeCompare(a[1].installed_at || '')
+    );
+    if (entries.length === 0) throw new Error('No path provided and no installed skills.');
+    const [lastId, lastRec] = entries[0];
+    dir = lastRec.path;
+    const parts = splitSkillId(lastId);
+    skillOrg = parts.org;
+    skillUser = parts.user;
+    skillName = parts.name;
+    console.log(`Publishing from: ${dir}`);
+  }
+
+  const skillMd = join(dir, 'SKILL.md');
+  if (!existsSync(skillMd)) throw new Error('SKILL.md not found at ' + dir);
+  const content = readFileSync(skillMd, 'utf8');
+  const meta = parseFrontmatter(content);
+  if (!meta) throw new Error('Invalid SKILL.md frontmatter');
+
+  const org = skillOrg || cfg.org;
+  const user = skillUser || (await api.whoami()).user;
+  const name = skillName || meta.name;
+  if (!org || !user || !name) throw new Error('Cannot infer org/user/name. Provide --path or install the skill first.');
+
+  const files = collectFiles(dir);
+  const result = await api.publish(org, user, name, args.message || '', files);
+  console.log(`Published ${result.id}@${result.version}`);
+}
+
+export async function cmdImport(args) {
+  const cfg = loadConfig();
+  const st = loadState();
+  const agents = detectAgents();
+
+  // Find unmanaged skills in agent dirs
+  const unmanaged = new Map(); // name -> { sources: [{agent, path}] }
+  const managedLinks = new Set(Object.keys(st.installed).map(linkNameForSkill));
+
+  for (const [agentName, agentPath] of Object.entries(agents)) {
+    if (!existsSync(agentPath)) continue;
+    for (const entry of readdirSync(agentPath, { withFileTypes: true })) {
+      const full = join(agentPath, entry.name);
+      // Skip managed symlinks
+      if (managedLinks.has(entry.name)) continue;
+      // Skip if it's a symlink pointing into our managed store
+      try {
+        if (lstatSync(full).isSymbolicLink()) {
+          const target = readlinkSync(full);
+          if (target.includes('skill-sharer')) continue;
+        }
+      } catch { /* ok */ }
+
+      // Check if it has SKILL.md
+      const skillMd = entry.isDirectory() ? join(full, 'SKILL.md') :
+        (lstatSync(full).isSymbolicLink() ? join(resolve(readlinkSync(full)), 'SKILL.md') : null);
+      if (!skillMd || !existsSync(skillMd)) continue;
+
+      const name = entry.name;
+      if (!unmanaged.has(name)) unmanaged.set(name, { sources: [] });
+      unmanaged.get(name).sources.push({ agent: agentName, path: full, skillMdPath: skillMd });
+    }
+  }
+
+  if (args.path) {
+    const p = resolve(args.path);
+    const skillMd = join(p, 'SKILL.md');
+    if (!existsSync(skillMd)) throw new Error(`No SKILL.md found at ${p}`);
+    const meta = parseFrontmatter(readFileSync(skillMd, 'utf8'));
+    const name = meta?.name || p.split('/').pop();
+    unmanaged.clear();
+    unmanaged.set(name, { sources: [{ agent: 'manual', path: p, skillMdPath: skillMd }] });
+  }
+
+  if (unmanaged.size === 0) {
+    if (!args.quiet) console.log('No unmanaged skills found.');
+    return;
+  }
+
+  console.log(`Found ${unmanaged.size} unmanaged skill(s):`);
+  for (const [name, info] of unmanaged) {
+    const agentList = info.sources.map(s => s.agent).join(', ');
+    console.log(`  ${name} (${agentList})`);
+  }
+
+  if (!cfg.org || !cfg.token) {
+    console.log('Skipping import — not logged in.');
+    return;
+  }
+
+  const me = await api.whoami();
+
+  for (const [name, info] of unmanaged) {
+    const source = info.sources[0]; // pick first as canonical
+    const dir = lstatSync(source.path).isSymbolicLink() ? resolve(readlinkSync(source.path)) : source.path;
+    const skillMdContent = readFileSync(join(dir, 'SKILL.md'), 'utf8');
+    const meta = parseFrontmatter(skillMdContent);
+    const skillName = meta?.name || name;
+    const id = `${cfg.org}/${me.user}/${skillName}`;
+
+    try {
+      // Publish to server
+      const files = collectFiles(dir);
+      const result = await api.publish(cfg.org, me.user, skillName, 'Imported from local agent', files);
+
+      // Write to managed store
+      const dest = managedPath(id, result.version);
+      mkdirSync(dest, { recursive: true });
+      for (const [fp, content] of Object.entries(files)) {
+        const full = join(dest, fp);
+        mkdirSync(join(full, '..'), { recursive: true });
+        writeFileSync(full, content);
+      }
+
+      // Remove originals and create symlinks
+      const linkName = linkNameForSkill(id);
+      for (const s of info.sources) {
+        try { rmSync(s.path, { recursive: true, force: true }); } catch { /* ok */ }
+      }
+      for (const [agentName, agentPath] of Object.entries(agents)) {
+        const link = join(agentPath, linkName);
+        try { unlinkSync(link); } catch { /* ok */ }
+        symlinkSync(dest, link);
+      }
+
+      // Update state
+      st.installed[id] = {
+        version: result.version,
+        installed_at: new Date().toISOString(),
+        path: dest,
+        agents: Object.keys(agents).sort(),
+        checksums: computeChecksums(dest),
+      };
+
+      console.log(`  ✓ ${name} → ${id}@${result.version}`);
+    } catch (e) {
+      console.error(`  ✗ ${name}: ${e.message}`);
+    }
+  }
+
+  saveState(st);
+}
+
+export async function cmdDoctor(args) {
+  const st = loadState();
+  const agents = detectAgents();
+  let issues = 0;
+
+  for (const [id, rec] of Object.entries(st.installed).sort()) {
+    const status = verifyInstall(id, rec, agents);
+    console.log(`${id}: ${status}`);
+
+    if (status !== 'ok' && !args.dry) {
+      // Attempt fix
+      if (status === 'broken-link') {
+        const linkName = linkNameForSkill(id);
+        for (const agentName of rec.agents) {
+          const agentPath = agents[agentName];
+          if (!agentPath) continue;
+          const link = join(agentPath, linkName);
+          try { unlinkSync(link); } catch { /* ok */ }
+          if (existsSync(rec.path)) {
+            symlinkSync(rec.path, link);
+            console.log(`  Fixed: ${link}`);
+          }
+        }
+      }
+      issues++;
+    } else if (status !== 'ok') {
+      issues++;
+    }
+  }
+
+  // Check for unmanaged
+  const managedLinks = new Set(Object.keys(st.installed).map(linkNameForSkill));
+  for (const [agentName, agentPath] of Object.entries(agents)) {
+    if (!existsSync(agentPath)) continue;
+    for (const entry of readdirSync(agentPath)) {
+      if (!managedLinks.has(entry) && !entry.startsWith('.')) {
+        const full = join(agentPath, entry);
+        if (existsSync(join(full, 'SKILL.md')) || (lstatSync(full).isSymbolicLink())) {
+          console.log(`Unmanaged: ${agentName}/${entry} — use: skills import`);
+          issues++;
+        }
+      }
+    }
+  }
+
+  if (issues === 0) console.log('All good.');
+  else console.log(`\n${issues} issue(s) found.`);
+}
+
+export async function cmdShare(args) {
+  const cfg = loadConfig();
+  const id = await resolveSkillId(args.skill, cfg);
+  const { org, user, name } = splitSkillId(id);
+  const role = args.maintain ? 'maintainer' : 'reader';
+  await api.grantAccess(org, user, name, args.with, role);
+  console.log(`Granted ${role} to ${args.with} on ${id}`);
+}
+
+export async function cmdUnshare(args) {
+  const cfg = loadConfig();
+  const id = await resolveSkillId(args.skill, cfg);
+  const { org, user, name } = splitSkillId(id);
+  await api.revokeAccess(org, user, name, args.from);
+  console.log(`Revoked access for ${args.from} on ${id}`);
+}
+
+export async function cmdVisibility(args) {
+  const cfg = loadConfig();
+  const id = await resolveSkillId(args.skill, cfg);
+  const { org, user, name } = splitSkillId(id);
+
+  if (!args.value) {
+    const data = await api.getAcl(org, user, name);
+    console.log(data.visibility);
+    return;
+  }
+
+  await api.setVisibility(org, user, name, args.value);
+  console.log(`Set ${id} visibility to ${args.value}`);
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@npeercy/skills",
+  "version": "0.1.0",
+  "description": "CLI-first skill marketplace for coding agents",
+  "type": "module",
+  "bin": {
+    "skills": "./bin/skills.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["skills", "agents", "claude", "pi"],
+  "license": "MIT"
+}