feat: claude skills feature

Author: Alex Holmberg

installer/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "syncable",
+  "owner": {
+    "name": "Syncable",
+    "email": "support@syncable.dev"
+  },
+  "metadata": {
+    "description": "Syncable CLI skills for AI coding agents — project analysis, security, vulnerabilities, dependencies, IaC validation, and cloud deployment.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "syncable-cli-skills",
+      "source": "./plugins/syncable-cli-skills",
+      "description": "Syncable CLI skills for project analysis, security scanning, vulnerability detection, dependency auditing, IaC validation, and cloud deployment.",
+      "version": "0.1.0"
+    }
+  ]
+}

installer/plugins/syncable-cli-skills/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "syncable-cli-skills",
+  "description": "Syncable CLI skills for project analysis, security scanning, vulnerability detection, dependency auditing, IaC validation, Kubernetes optimization, and cloud deployment.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Syncable",
+    "email": "support@syncable.dev"
+  },
+  "homepage": "https://syncable.dev",
+  "license": "MIT",
+  "keywords": ["syncable", "devops", "security", "deployment", "kubernetes", "docker", "iac"]
+}

installer/src/commands/install.ts

@@ -1,22 +1,17 @@
 import fs from 'fs';
 import path from 'path';
 import { Skill, loadSkills, getBundledSkillsDir } from '../skills.js';
-import { transformForClaude } from '../transformers/claude.js';
+import { installClaudePlugin } from '../transformers/claude.js';
 import { transformForCodex } from '../transformers/codex.js';
 import { transformForCursor } from '../transformers/cursor.js';
 import { transformForWindsurf } from '../transformers/windsurf.js';
 import { transformForGemini } from '../transformers/gemini.js';
 import { SKILL_MARKER_START, SKILL_MARKER_END } from '../constants.js';
 
-export function writeSkillsForClaude(skills: Skill[], destDir: string): void {
-  for (const skill of skills) {
-    const results = transformForClaude(skill);
-    for (const { relativePath, content } of results) {
-      const fullPath = path.join(destDir, relativePath);
-      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-      fs.writeFileSync(fullPath, content);
-    }
-  }
+export function writeSkillsForClaude(skills: Skill[], _destDir: string): void {
+  // Claude Code uses the plugin marketplace system — destDir is ignored.
+  // Skills are installed as a plugin at ~/.claude/plugins/cache/syncable/...
+  installClaudePlugin(skills);
 }
 
 export function writeSkillsForCodex(skills: Skill[], destDir: string): void {

installer/src/commands/status.ts

@@ -2,12 +2,22 @@ import fs from 'fs';
 import path from 'path';
 import { AgentName } from '../agents/types.js';
 import { SKILL_MARKER_START } from '../constants.js';
+import { getClaudePluginCacheDir } from '../transformers/claude.js';
 
 export function countInstalledSkills(dirOrPath: string, agent: AgentName | string): number {
   if (!fs.existsSync(dirOrPath)) return 0;
 
   switch (agent) {
     case 'claude': {
+      // Check plugin cache location
+      const cacheDir = getClaudePluginCacheDir();
+      const skillsDir = path.join(cacheDir, 'skills');
+      if (fs.existsSync(skillsDir)) {
+        return fs.readdirSync(skillsDir)
+          .filter((f) => fs.statSync(path.join(skillsDir, f)).isDirectory())
+          .length;
+      }
+      // Fallback: check old location
       let count = 0;
       for (const sub of ['commands', 'workflows']) {
         const dir = path.join(dirOrPath, sub);

installer/src/index.ts

@@ -20,6 +20,7 @@ import {
   InstallOptions,
 } from './commands/install.js';
 import { removeSyncableSkills, removeGeminiSection } from './commands/uninstall.js';
+import { uninstallClaudePlugin } from './transformers/claude.js';
 import { countInstalledSkills } from './commands/status.js';
 
 const require = createRequire(import.meta.url);
@@ -243,7 +244,7 @@ program
         const dest = agent.getSkillPath();
         switch (agent.name) {
           case 'claude':
-            removeSyncableSkills(dest);
+            uninstallClaudePlugin();
             break;
           case 'codex':
             removeSyncableSkills(dest, 'syncable-*');

installer/src/transformers/claude.ts

@@ -1,8 +1,213 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
 import { Skill } from '../skills.js';
 import { TransformResult } from './types.js';
 
+const PLUGIN_NAME = 'syncable-cli-skills';
+const PLUGIN_VERSION = '0.1.0';
+const MARKETPLACE_NAME = 'syncable';
+
+/**
+ * Transform a skill into Claude Code plugin format.
+ * Each skill becomes a directory with SKILL.md inside skills/<skill-name>/
+ */
 export function transformForClaude(skill: Skill): TransformResult[] {
-  const dir = skill.category === 'command' ? 'commands' : 'workflows';
-  const content = `---\nname: ${skill.frontmatter.name}\ndescription: ${skill.frontmatter.description}\n---\n\n${skill.body}`;
-  return [{ relativePath: `${dir}/${skill.filename}`, content }];
+  // Skill name from filename (strip .md extension)
+  const skillName = skill.filename.replace(/\.md$/, '');
+
+  // Build YAML-safe description (double-quoted, no inner unescaped quotes)
+  const safeDesc = skill.frontmatter.description
+    .replace(/"/g, '\\"')
+    .replace(/: /g, ' - ') // Remove colons that break YAML
+    .replace(/Trigger on:.*$/, '') // Strip trigger phrases
+    .trim();
+
+  // Only description in frontmatter — directory name is the skill name
+  const content = `---\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
+
+  return [{ relativePath: `skills/${skillName}/SKILL.md`, content }];
+}
+
+/**
+ * Get the plugin cache directory for Claude Code.
+ */
+export function getClaudePluginCacheDir(): string {
+  return path.join(
+    os.homedir(),
+    '.claude',
+    'plugins',
+    'cache',
+    MARKETPLACE_NAME,
+    PLUGIN_NAME,
+    PLUGIN_VERSION
+  );
+}
+
+/**
+ * Write the plugin.json manifest.
+ */
+function writePluginManifest(cacheDir: string): void {
+  const manifestDir = path.join(cacheDir, '.claude-plugin');
+  fs.mkdirSync(manifestDir, { recursive: true });
+
+  const manifest = {
+    name: PLUGIN_NAME,
+    description:
+      'Syncable CLI skills for project analysis, security scanning, vulnerability detection, dependency auditing, IaC validation, Kubernetes optimization, and cloud deployment.',
+    version: PLUGIN_VERSION,
+    author: {
+      name: 'Syncable',
+      email: 'support@syncable.dev',
+    },
+    homepage: 'https://syncable.dev',
+    license: 'MIT',
+    keywords: ['syncable', 'devops', 'security', 'deployment', 'kubernetes', 'docker', 'iac'],
+  };
+
+  fs.writeFileSync(path.join(manifestDir, 'plugin.json'), JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Register the plugin in installed_plugins.json.
+ */
+function registerPlugin(cacheDir: string): void {
+  const pluginsFile = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+
+  let data: { version: number; plugins: Record<string, unknown[]> } = { version: 2, plugins: {} };
+
+  if (fs.existsSync(pluginsFile)) {
+    try {
+      data = JSON.parse(fs.readFileSync(pluginsFile, 'utf-8'));
+    } catch {
+      // Corrupted file — start fresh
+      data = { version: 2, plugins: {} };
+    }
+  }
+
+  const key = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+  const now = new Date().toISOString();
+
+  data.plugins[key] = [
+    {
+      scope: 'user',
+      installPath: cacheDir,
+      version: PLUGIN_VERSION,
+      installedAt: now,
+      lastUpdated: now,
+    },
+  ];
+
+  fs.mkdirSync(path.dirname(pluginsFile), { recursive: true });
+  fs.writeFileSync(pluginsFile, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Register the marketplace in known_marketplaces.json so Claude Code knows about it.
+ */
+function registerMarketplace(): void {
+  const marketFile = path.join(os.homedir(), '.claude', 'plugins', 'known_marketplaces.json');
+
+  let data: Record<string, unknown> = {};
+
+  if (fs.existsSync(marketFile)) {
+    try {
+      data = JSON.parse(fs.readFileSync(marketFile, 'utf-8'));
+    } catch {
+      data = {};
+    }
+  }
+
+  // Only add if not already present
+  if (!data[MARKETPLACE_NAME]) {
+    data[MARKETPLACE_NAME] = {
+      source: {
+        source: 'github',
+        repo: 'syncable-dev/syncable-cli',
+      },
+      installLocation: path.join(os.homedir(), '.claude', 'plugins', 'marketplaces', MARKETPLACE_NAME),
+      lastUpdated: new Date().toISOString(),
+    };
+
+    fs.writeFileSync(marketFile, JSON.stringify(data, null, 2));
+  }
+}
+
+/**
+ * Full Claude Code plugin installation:
+ * 1. Write SKILL.md files into plugin cache
+ * 2. Write plugin.json manifest
+ * 3. Register in installed_plugins.json
+ * 4. Register marketplace in known_marketplaces.json
+ */
+export function installClaudePlugin(skills: Skill[]): { cacheDir: string; skillCount: number } {
+  const cacheDir = getClaudePluginCacheDir();
+
+  // Clear old skills
+  const skillsDir = path.join(cacheDir, 'skills');
+  if (fs.existsSync(skillsDir)) {
+    fs.rmSync(skillsDir, { recursive: true });
+  }
+
+  // Write each skill as skills/<name>/SKILL.md
+  for (const skill of skills) {
+    const results = transformForClaude(skill);
+    for (const { relativePath, content } of results) {
+      const fullPath = path.join(cacheDir, relativePath);
+      fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+      fs.writeFileSync(fullPath, content);
+    }
+  }
+
+  // Write plugin manifest
+  writePluginManifest(cacheDir);
+
+  // Register plugin
+  registerPlugin(cacheDir);
+
+  // Register marketplace
+  registerMarketplace();
+
+  return { cacheDir, skillCount: skills.length };
+}
+
+/**
+ * Remove the Claude Code plugin.
+ */
+export function uninstallClaudePlugin(): void {
+  const cacheDir = getClaudePluginCacheDir();
+
+  // Remove cache directory
+  if (fs.existsSync(cacheDir)) {
+    fs.rmSync(cacheDir, { recursive: true });
+  }
+
+  // Remove from installed_plugins.json
+  const pluginsFile = path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+  if (fs.existsSync(pluginsFile)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(pluginsFile, 'utf-8'));
+      const key = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+      delete data.plugins[key];
+      fs.writeFileSync(pluginsFile, JSON.stringify(data, null, 2));
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  // Also clean up old-style flat skills if they exist
+  const oldSkillsDir = path.join(os.homedir(), '.claude', 'skills', 'syncable');
+  if (fs.existsSync(oldSkillsDir)) {
+    fs.rmSync(oldSkillsDir, { recursive: true });
+  }
+
+  // Clean up flat files from failed earlier installs
+  const flatSkillsDir = path.join(os.homedir(), '.claude', 'skills');
+  if (fs.existsSync(flatSkillsDir)) {
+    for (const file of fs.readdirSync(flatSkillsDir)) {
+      if (file.startsWith('syncable-') && file.endsWith('.md')) {
+        fs.unlinkSync(path.join(flatSkillsDir, file));
+      }
+    }
+  }
 }

skills/commands/syncable-dependencies.md

@@ -49,24 +49,25 @@ sync-ctl dependencies <PATH> --licenses --prod-only --agent
 
 ## Reading Results
 
-When you use `--agent`, the output is a compressed summary. License distribution and dependency counts are always included. Individual package details are available via retrieve for large dependency trees.
+When you use `--agent`, the output is a **compressed summary** with counts, license distribution, and source breakdown. Individual package details are NOT in the compressed output — use `sync-ctl retrieve` to get them.
 
-The output JSON includes:
-- `summary` — total counts, license distribution, prod/dev split
-- `license_concerns` — packages with copyleft or unknown licenses
-- `full_data_ref` — reference ID for retrieving full data
-- `retrieval_hint` — exact command for drill-down
+**What's in the compressed output:**
+- `total` — total dependency count
+- `production` / `development` — prod vs dev split
+- `by_source` — counts per ecosystem (npm, crates.io, pypi, etc.)
+- `by_license` — license distribution
+- `full_data_ref` — reference ID for the full data
 
-To drill into specifics:
+**To get individual package details, use retrieve:**
 ```bash
-# Get high-severity license findings
-sync-ctl retrieve <ref_id> --query "severity:high"
+# Get the full dependency list
+sync-ctl retrieve <ref_id>
 
-# Get findings for a specific file
+# Search for a specific package
 sync-ctl retrieve <ref_id> --query "file:package.json"
 ```
 
-**Available query filters:** `severity:<level>`, `file:<path>`
+Results are paginated (default 20). Use `--limit N --offset M` for more.
 
 ## Error Handling