🧠 @skillx-map/core

The zero-dependency core engine for skillX — managing AI coding-assistant skills and plugins.

This package owns platform scanning, item type detection, validation, safe trash, and restoration behavior. It exposes platform-neutral TypeScript APIs used by the skillx-map CLI and the @skillx-map/web local Express server.

📦 Installation

Add the library to your dependencies:

pnpm add @skillx-map/core
# or
npm install @skillx-map/core

🛠️ API Reference

1. scanManagedItems(options: ScanOptions)

Walks Claude Code, Codex, and Gemini (Agents) roots under the specified cwd and homeDir, classifying entries and generating health flags.

import { scanManagedItems } from '@skillx-map/core';

const result = await scanManagedItems({
  cwd: process.cwd(),
  homeDir: os.homedir()
});

console.log(result.items);    // list of ManagedItem
console.log(result.warnings); // list of ScanWarning (e.g. broken symlinks, missing paths)

2. inspectManagedItem(item: ManagedItem)

Inspects an item in-depth, reading its manifest, readme content, and YAML frontmatter configuration metadata if present.

3. trashManagedItem(item: ManagedItem, options: TrashOptions)

Moves a skill folder safely to the local recoverable trash folder under .skillx/trash and creates a backup manifest JSON.

import { trashManagedItem } from '@skillx-map/core';

const manifest = await trashManagedItem(item, {
  trashRoot: './.skillx/trash'
});

4. restoreManagedItem(manifest: TrashManifest)

Restores a previously trashed skill folder back to its original path, verifying there is no file collision before doing so.

🔎 Platforms & Paths Scanned

• Claude Code: ~/.claude/skills, ~/.claude/plugins, .claude/skills, .claude/plugins
• Codex: ~/.codex/skills, ~/.codex/plugins, .codex/skills, .codex/plugins
• Gemini (Agents): ~/.gemini/config/skills, ~/.gemini/config/plugins, .agents/skills, .agents/plugins

🔗 Links

• Repository: GitHub - kanziman/skillx-map
• Main CLI: skillx-map
• Web App: @skillx-map/web