CLI Command Reference
Relevant source files
The following files were used as context for generating this wiki page:
SkillKit provides a comprehensive Command Line Interface (CLI) designed to manage, translate, and synchronize AI agent skills across multiple coding environments. The CLI serves as the primary entry point for users to interact with the skill ecosystem, supporting everything from skill creation and validation to cross-agent format translation for 17 different AI agents.
The architecture follows a modular pattern where the CLI layer (using clipanion) interacts with core logic packages for translation, recommendation, and synchronization. This allows for a consistent experience whether a user is using claude-code, cursor, windsurf, or other supported platforms.
Sources: README.md:1-20, packages/cli/src/commands/create.ts:7-15
Skill Lifecycle Management
SkillKit handles the entire lifecycle of a skill, from initialization to execution. Users can create new skills with standardized directory structures, validate them against the Agent Skills specification, and read their contents to verify agent instructions.
Creation and Structure
The create command (also aliased as new) generates a standardized skill directory. By default, it creates a SKILL.md file with a human-readable title derived from the skill name. Optional flags allow for the inclusion of references/, scripts/, and assets/ directories to bundle resources with the instruction set.
The diagram above illustrates the logic flow of the CreateCommand class.
Sources: packages/cli/src/commands/create.ts:31-110, README.md:275-300
Validation and Listing
The validate command ensures that SKILL.md files comply with the Agent Skills specification, checking for required frontmatter fields like name and description. It also enforces naming conventions (lowercase alphanumeric with hyphens) and length constraints.
| Command | Purpose | Key Flags |
|---|---|---|
list | Lists all discovered skills in the current project or global path | --json (machine-readable output) |
validate | Checks skill compliance with the specification | N/A |
read | Outputs the instruction content of a specific skill | N/A |
Sources: e2e/core-commands.e2e.test.ts:76-155, packages/cli/src/commands/create.ts:40-45
Cross-Agent Translation
SkillKit's core capability is the ability to translate skills between 17 different AI agents. This system uses a "Canonical" intermediate format to ensure metadata and specific agent fields (like Claude's hooks or Cursor's globs) are preserved or flagged when incompatible.
Translation Logic
The translation process involves parsing a source SKILL.md into a CrossAgentSkill object and then applying agent-specific transformations.
The sequence diagram shows how the SkillTranslator mediates between raw files and agent-specific outputs.
Sources: packages/core/src/skill-translator.ts:98-150, packages/core/src/skill-translator.ts:187-215
Supported Agent Formats
The system supports a variety of configuration formats depending on the target agent:
| Format Type | Agent Examples | Description |
|---|---|---|
| XML | Claude Code, Roo, Clawdbot | Uses <skills_system> tags with specialized <usage> blocks. |
| MDC | Cursor | Uses .mdc files with YAML frontmatter containing globs and alwaysApply. |
| Markdown | Windsurf, Trae, GitHub Copilot | Standard H3-level headers for each skill and Invoke: commands. |
| JSON | Gemini CLI | Machine-readable array of skill objects including invoke paths. |
| Table | Codex | A formatted Markdown table listing skills and descriptions. |
Sources: packages/core/src/skill-translator.ts:360-490, packages/core/src/tests/skill-translator.test.ts:47-75
Slash Command Generation
The CommandGenerator transforms skills into agent-native slash commands (e.g., /test or @test). This allows agents to invoke skill functionality via natural language triggers or explicit command calls.
Generator Architecture
The generator supports different command styles:
- Claude Code: Generates individual
.mdfiles in.claude/commands/with dedicatedargsandusageexamples. - Cursor: Generates a centralized
.cursorrules(or MDC equivalent) where commands are represented as@-mentions. - OpenCode/Copilot: Generates command metadata files that specify parameters and skill references.
The flow shows how a single skill can be broadcasted into multiple command formats.
Sources: packages/core/src/commands/generator.ts:145-310, packages/core/src/commands/tests/commands.test.ts:460-500
Synchronization and Discovery
The sync and recommend commands manage the integration of skills into the local development environment.
Sync Process
The sync command automates the generation of agent-specific configuration files (like CLAUDE.md or .cursorrules). It gathers all enabled skills and produces the config content required for the agent to "see" and utilize those skills. It handles path resolution and ensures that the invokeCommand (defaulting to skillkit read) is correctly formatted.
Sources: packages/core/src/skill-translator.ts:327-355, e2e/translation.e2e.test.ts:250-265
Recommendation Engine
The recommend command analyzes project context (e.g., detecting package.json for Node.js, Cargo.toml for Rust, or requirements.txt for Python) and matches it against available skill tags.
Sources: e2e/translation.e2e.test.ts:150-180, README.md:120-135
Technical Summary
The SkillKit CLI is built upon the following data structures and interfaces:
CrossAgentSkill: The canonical representation containing body content, frontmatter, andagentFields.AgentSkillFormat: Configuration definingskillsDir,configFile, andconfigFormat(XML, MDC, JSON, etc.).SkillTranslationResult: Object containing translated content along with lists ofwarningsorincompatiblefeatures.
Sources: packages/core/src/skill-translator.ts:50-75, packages/core/src/commands/generator.ts:15-60