High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
SkillKit is a modular framework designed to provide portable, reusable instructions (skills) across multiple AI coding agents. It serves as a translation and orchestration layer that abstracts the differences between various AI agent ecosystems, allowing developers to write instructions once and deploy them to any supported agent.
The architecture is built around a "Write Once, Use Everywhere" philosophy, centralizing skill discovery, translation, recommendation, and execution. By standardizing the SKILL.md format, SkillKit enables a cross-agent ecosystem where domain-specific knowledge and methodology frameworks can be shared regardless of the underlying AI tool (e.g., Claude Code, Cursor, or Windsurf).
Sources: README.md:10-25, packages/core/src/skill-translator.ts:1-10
System Overview
SkillKit is organized as a monorepo containing several specialized packages and applications that handle different stages of the skill lifecycle.
Core Components
| Component | Package Path | Primary Responsibility |
|---|---|---|
| Core | packages/core | Shared logic for discovery, parsing, translation, and recommendation. |
| CLI | packages/cli | The main command-line entry point for user interaction. |
| Agents | packages/agents | Specialized adapters for 17+ different AI coding agents. |
| TUI | packages/tui | Terminal-based User Interface for interactive management. |
Sources: CONTRIBUTING.md:46-56, README.md:143-160
The following diagram illustrates the relationship between the user, the SkillKit core logic, and the target AI agent environments.
The diagram shows the flow from user input through the core processing engine to specific agent adapters.
Sources: CONTRIBUTING.md:46-56, packages/core/src/skill-translator.ts:11-30
Data Models and Specifications
The Skill Specification
The fundamental unit of data in SkillKit is the Skill, defined primarily in a SKILL.md file. It follows a specific schema that includes YAML frontmatter for metadata and Markdown for instruction content.
| Field | Type | Description |
|---|---|---|
name | String | Unique identifier (lowercase alphanumeric with hyphens). |
description | String | Brief summary of what the skill does for agent triggers. |
version | String | Semantic version of the skill. |
tags | Array | Categorization tags for discovery and recommendation. |
allowed-tools | String | List of pre-approved tools the skill may use. |
Sources: schemas/skill.schema.json:10-58, packages/core/src/skill-translator.ts:40-55
Canonical Representation
During processing, SkillKit converts agent-specific formats into a CrossAgentSkill canonical format. This ensures that internal logic remains decoupled from specific agent requirements.
export interface CrossAgentSkill {
name: string;
description: string;
content: string;
frontmatter: Record<string, unknown>;
sourcePath: string;
sourceAgent?: AgentType;
version?: string;
tags?: string[];
agentFields?: Record<string, unknown>;
}
Sources: packages/core/src/skill-translator.ts:39-53
Skill Translation Engine
The translation engine is the architectural heart of SkillKit. It handles the conversion of canonical skills into agent-specific formats (e.g., XML for Claude Code, MDC for Cursor, or JSON for Gemini CLI).
This sequence shows the transformation of a generic skill into an agent-specific configuration.
Sources: packages/core/src/skill-translator.ts:184-250, packages/core/src/skill-translator.ts:318-340
Formatting Strategies
The translator uses different configFormat strategies based on the target agent's requirements:
- XML: Used by Claude Code and OpenCode for structured system prompts.
- MDC: Multi-Document Context used by Cursor.
- Markdown Table: Used by Codex for quick indexing.
- JSON: Used for structured data integration in Gemini CLI.
Sources: packages/core/src/skill-translator.ts:365-410, packages/core/src/skill-translator.ts:436-455
Recommendation Architecture
SkillKit includes a RecommendationEngine that analyzes project context to suggest relevant skills. It calculates a compatibility score based on several weighted factors.
Scoring Logic
The engine uses a ProjectProfile (containing stack info like frameworks, languages, and tools) to score skills using the following weights:
| Category | Max Weight | Logic |
|---|---|---|
| Framework | 40 | Matches based on TAG_TO_TECH mapping and explicit metadata. |
| Language | 20 | Checks for direct language compatibility (e.g., TypeScript). |
| Library | 15 | Matches project dependencies against skill requirements. |
| Tags | 10 | Matches skill tags against project patterns. |
| Quality/Freshness | 10 | Penalizes old skills and rewards verified/popular ones. |
Sources: packages/core/src/recommend/engine.ts:33-70, packages/core/src/recommend/engine.ts:98-130
This diagram describes the pipeline from source code analysis to final skill suggestions.
Sources: packages/core/src/recommend/engine.ts:310-350
Implementation Patterns
Agent Adapters
Agents are supported through a standardized adapter interface. For example, the ClawdbotAdapter identifies the agent presence by checking specific workspace paths like .clawdbot/skills or a global ~/.clawdbot directory. It then generates an AGENTS.md configuration file that includes usage notes and <available_skills> tags.
Sources: packages/agents/src/tests/clawdbot.test.ts:30-45, packages/agents/src/tests/clawdbot.test.ts:175-200
Skill Lifecycle Management
The CLI handles the creation and validation of skills. The create command generates a standardized directory structure including optional references, scripts, and assets folders, ensuring that skills are not just text instructions but can include bundled resources.
Structure:
[skill-name]/
├── SKILL.md
├── references/
├── scripts/
└── assets/
Sources: packages/cli/src/commands/create.ts:65-85
Summary
The SkillKit architecture provides a robust abstraction layer for AI agent instructions. By separating the Canonical Representation from Agent Adapters, the system allows for seamless translation between 17+ agent formats. The integration of a Recommendation Engine and a Context Manager ensures that the right skills are suggested and synchronized based on the specific technical stack of the user's project.