ccski 2.2.0 → 2.3.0

package/README.md

@@ -1,9 +1,21 @@
 # ccski – Claude Code Skills Manager
 
-ccski is a CLI + MCP server to discover, install, enable/disable, and serve Claude/Codex-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
 
 Requires Node.js >= 20.
@@ -43,15 +55,15 @@ MCP plugin config example (Codex/Cursor/Windsurf/VS Code):
 
 ### Core CLI commands
 
-| Command | Purpose |
-| --- | --- |
-| `ccski list` | List discovered skills (project, user, plugin) |
-| `ccski info <name>` | Show metadata and content preview |
-| `ccski install <source> [-i|--all|--path]` | Install from git/dir/marketplace/SKILL.md; interactive picker available |
-| `ccski enable [names...] [-i|--all]` | Enable skills (`.SKILL.md` -> `SKILL.md`) |
-| `ccski disable [names...] [-i|--all]` | Disable skills (`SKILL.md` -> `.SKILL.md`) |
-| `ccski validate <path>` | Validate SKILL.md or skill directory |
-| `ccski mcp` | Start MCP server (stdio/http/sse) |
+| Command                                         | Purpose                                                                        |
+| ----------------------------------------------- | ------------------------------------------------------------------------------ |
+| `ccski list`                                    | List discovered skills (project, user, plugin)                                 |
+| `ccski info <name>`                             | Show metadata and content preview                                              |
+| `ccski install <source> [-i\|--all\|--path]`    | Install from git/dir/marketplace/SKILL.md; interactive picker available        |
+| `ccski enable [names...] [-i\|--all]`           | Enable skills (`.SKILL.md` -> `SKILL.md`)                                      |
+| `ccski disable [names...] [-i\|--all]`          | Disable skills (`SKILL.md` -> `.SKILL.md`)                                     |
+| `ccski validate <path>`                         | Validate SKILL.md or skill directory                                           |
+| `ccski mcp`                                     | Start MCP server (stdio/http/sse)                                              |
 
 ### Install examples
 
@@ -77,7 +89,7 @@ ccski disable --all
 
 ## More
 
-- Programmatic API is available from the package export; see the docs site for API usage examples.
+- 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.
@@ -88,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`: built-ins `"agents" | "claude" | "codex" | "gemini" | "openclaw" | "file"` plus discovered `.<agent>/skills` providers
+- `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`