ccski 2.1.0 → 2.2.1

package/README.md

@@ -1,6 +1,20 @@
 # ccski – Claude Code Skills Manager
 
-ccski is a CLI + MCP server to discover, install, enable/disable, and serve Claude Code-compatible skills. This README covers install and usage. For architecture and UX philosophy, see `SPEC.md`.
+ccski is a CLI + MCP server to discover, install, enable/disable, and serve Claude/Codex-compatible skills. It also exports a small “kernel” API so you can embed discovery/validation in your own scripts. This README covers install and usage. For architecture and UX philosophy, see `SPEC.md`.
+
+Documentation site: https://jixoai-labs.github.io/ccski/
+
+## Table of contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+  - [Run MCP server](#run-mcp-server)
+  - [Core CLI commands](#core-cli-commands)
+  - [Install examples](#install-examples)
+  - [Enable/disable](#enabledisable)
+- [More](#more)
+- [Acknowledgements](#acknowledgements)
+- [API Reference](#api-reference)
 
 ## Install
 
@@ -75,6 +89,7 @@ ccski disable --all
 
 ## More
 
+- Programmatic API is available from the package export; see [API Reference](#api-reference) (or the docs site) for usage examples.
 - Claude users: prefer `ccski mcp --exclude=claude` to avoid echoing built-in Claude skills.
 - Codex users: prefer `ccski mcp --exclude=codex` when avoid echoing built-in Codex skills.
 - All commands support `--json` for scripting.
@@ -85,3 +100,158 @@ ccski disable --all
 
 - [openskills](https://github.com/numman-ali/openskills) — established the SKILL.md authoring pattern; ccski aligns with that spec.
 - [universal-skills](https://github.com/klaudworks/universal-skills) — MCP-first skill set; ccski focuses on management, not bundling content.
+
+## API Reference
+
+Public exports from `import ... from "ccski"`.
+
+Notes:
+
+- Package is ESM (`"type": "module"`). Use `import` in Node.js >= 20.
+- `discoverSkills()` / `SkillRegistry.getAll()` return **metadata**. Use `loadSkill()` / `SkillRegistry.load()` to read full SKILL.md content.
+
+### Importing
+
+```ts
+import { discoverSkills, SkillRegistry, validateSkillFile } from "ccski";
+import type { Skill, SkillMetadata } from "ccski";
+```
+
+### Types
+
+- `SkillProvider`: `"claude" | "codex" | "file"`
+- `SkillLocation`: `"user" | "project" | "plugin"`
+- `SkillFrontmatter`: required SKILL.md frontmatter shape (`name`, `description`, plus extra fields)
+- `SkillMetadata`: discovered skill summary (name/description/provider/location/path + bundled resources flags)
+- `Skill`: `SkillMetadata` + `content` (full markdown, including frontmatter) + `fullName`
+- `ParseResult`: `{ frontmatter, content, fullContent }`
+- `DiscoveryOptions`: configure default roots, custom directories, provider tagging, and disabled-skill handling
+- `SkillRegistryOptions`: `DiscoveryOptions` + plugin discovery options (`pluginsFile`, `pluginsRoot`, `settingsFile`, `userDir`)
+
+Reference shapes (simplified):
+
+```ts
+export interface SkillMetadata {
+  name: string;
+  description: string;
+  disabled?: boolean;
+  provider: "claude" | "codex" | "file";
+  location: "user" | "project" | "plugin";
+  path: string;
+  hasReferences: boolean;
+  hasScripts: boolean;
+  hasAssets: boolean;
+  pluginInfo?: { pluginName: string; marketplace: string; version: string };
+}
+
+export interface Skill extends SkillMetadata {
+  content: string; // full markdown (including frontmatter)
+  fullName: string;
+}
+```
+
+### Errors
+
+All errors extend `CcskiError` and include a `suggestions: string[]` field for UX-friendly guidance.
+
+- `SkillNotFoundError`: thrown when a skill name cannot be resolved
+- `AmbiguousSkillNameError`: thrown when multiple skills match; includes `matches: string[]`
+- `ParseError`: SKILL.md read/UTF-8/frontmatter parsing failures; includes `filePath`, `reason`
+- `ValidationError`: frontmatter schema validation failures; includes `filePath`, `issues: string[]`
+
+### Parser
+
+#### `parseSkillFile(filePath: string): ParseResult`
+
+Parse a `SKILL.md` (or `.SKILL.md`) file and return:
+
+- `frontmatter`: validated & normalized (`description` whitespace is normalized)
+- `content`: markdown body **without** frontmatter
+- `fullContent`: original file content **including** frontmatter
+
+Throws `ParseError` (IO/encoding/YAML) and `ValidationError` (schema).
+
+#### `validateSkillFile(filePath: string): { success; errors; suggestions }`
+
+Safe validator wrapper around `parseSkillFile()`:
+
+- `success: true` when file is valid
+- otherwise returns `errors` and `suggestions` without throwing
+
+```ts
+import { validateSkillFile } from "ccski";
+
+const result = validateSkillFile("/abs/path/to/SKILL.md");
+if (!result.success) {
+  console.error(result.errors);
+  console.error(result.suggestions);
+}
+```
+
+### Discovery
+
+#### `getDefaultSkillDirectories(userDir: string)`
+
+Return the default search roots (project + user) with provider tagging (Claude/Codex).
+
+#### `discoverSkills(options?: DiscoveryOptions): { skills; diagnostics }`
+
+Scan built-in directories (unless `scanDefaultDirs: false`) plus `customDirs`.
+
+- `skills`: `SkillMetadata[]`
+- `diagnostics`: scanned paths, warnings, conflicts, and counts by provider
+
+```ts
+import { discoverSkills } from "ccski";
+
+const { skills, diagnostics } = discoverSkills({
+  includeDisabled: true,
+  customDirs: ["/extra/skills"],
+  customProvider: "file",
+});
+```
+
+#### `loadSkill(metadata: SkillMetadata): Skill`
+
+Load a discovered skill’s full content (reads `SKILL.md` or `.SKILL.md` based on `metadata.disabled`).
+
+#### `scanSkillDirectory(dirPath, options, provider, userDir?, scope?)`
+
+Lower-level scanner used by `discoverSkills()`. Useful when you want full control over:
+
+- root path + recursion
+- provider tagging (`"claude" | "codex" | "file"`)
+- optional `scope` prefixing for names
+
+### Registry
+
+#### `new SkillRegistry(options?: SkillRegistryOptions)`
+
+Convenience wrapper around discovery + fuzzy resolution.
+
+```ts
+import { SkillRegistry } from "ccski";
+
+const registry = new SkillRegistry({ includeDisabled: true });
+
+const all = registry.getAll(); // SkillMetadata[]
+const full = registry.load("some-skill"); // Skill (with content)
+```
+
+Methods:
+
+- `refresh()`: rescan directories (and plugins unless `skipPlugins: true`)
+- `getAll()`: list all discovered skills
+- `find(name)`: resolve a name (case-insensitive, supports short name and `provider:name`)
+- `has(name)`: boolean existence check
+- `load(name)`: resolve + read full content
+- `getDiagnostics()`: totals + scanned roots + warnings/conflicts
+
+### Schemas (Zod)
+
+These are exported for validating/parsing external JSON and frontmatter in a type-safe way:
+
+- `SkillFrontmatterSchema` / `SkillFrontmatterType`
+- `PluginEntrySchema` / `PluginEntryType`
+- `InstalledPluginsSchema` / `InstalledPluginsType`
+- `ClaudeSettingsSchema` / `ClaudeSettingsType`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccski",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Claude Code Skills Manager - CLI and MCP interface for managing skills across AI agents",
   "type": "module",
   "bin": {
@@ -57,6 +57,7 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
+    "vitepress": "^1.5.0",
     "yargs": "^17.7.2",
     "zod": "^3.24.1"
   },
@@ -73,6 +74,9 @@
     "test:coverage": "vitest run --coverage",
     "ts": "tsc --noEmit",
     "lint": "echo 'Linting not configured yet'",
-    "fmt": "prettier --write ."
+    "fmt": "prettier --write .",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   }
 }