Monorepo Structure

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• CONTRIBUTING.md
• README.md
• packages/core/src/skill-translator.ts
• packages/cli/src/commands/create.ts

SkillKit is organized as a monorepo designed to provide a universal skills loader for AI coding agents. The project uses pnpm workspaces and Turbo to manage multiple packages and applications within a single repository, ensuring shared logic, consistent tooling, and efficient builds across various components such as the core engine, CLI, and agent adapters.

Sources: package.json:1-5, CONTRIBUTING.md:46-48

Workspace Architecture

The monorepo separates concerns into two primary directories: apps/ and packages/. This structure allows the project to maintain a decoupled core logic while providing specific entry points for users, such as the CLI and Terminal UI.

Directory Layout

Directory	Component	Description
apps/skillkit	CLI Entry Point	The primary command-line interface for users to interact with SkillKit.
packages/core	@skillkit/core	The core engine containing shared logic for discovery, parsing, and translation.
packages/cli	@skillkit/cli	Command implementations and CLI-specific logic.
packages/tui	@skillkit/tui	Terminal User Interface components.
packages/agents	@skillkit/agents	Adapters for various AI coding agents.

Sources: CONTRIBUTING.md:49-60

Dependency and Build Flow

The following diagram illustrates the relationship between the internal packages and the build orchestration managed by Turborepo.

The apps/skillkit package serves as the distribution point, while packages/core acts as the foundational dependency for all other modules.

Sources: package.json:7-18, CONTRIBUTING.md:50-58

Core Modules Analysis

The functionality of SkillKit is distributed across several key directories within the packages/core workspace. These modules handle the lifecycle of a "Skill" from discovery to cross-agent translation.

Key Core Components

• Discovery: Responsible for scanning directories to find SKILL.md files.
• Parser: Handles the extraction of YAML frontmatter and Markdown body content from skill files.
• Translator: The engine that converts canonical skill representations into 17 different agent-specific formats (e.g., Claude Code, Cursor, Windsurf).
• Recommend: A recommendation engine that analyzes project stacks to suggest relevant skills.

Sources: CONTRIBUTING.md:52-56, packages/core/src/skill-translator.ts:32-55

Data Structure: Cross-Agent Skill

The CrossAgentSkill interface in packages/core/src/skill-translator.ts serves as the internal canonical representation used during the translation process.

export interface CrossAgentSkill {
  name: string;
  description: string;
  content: string;
  frontmatter: Record<string, unknown>;
  sourcePath: string;
  sourceAgent?: AgentType;
  version?: string;
  author?: string;
  tags?: string[];
  allowedTools?: string[];
  agentFields?: Record<string, unknown>;
}

Sources: packages/core/src/skill-translator.ts:50-63

Build and Development Workflow

The monorepo utilizes a standardized script set defined in the root package.json to manage the lifecycle of all internal packages.

Command Reference

Command	Action
pnpm build	Executes turbo run build across all workspaces.
pnpm test	Runs unit tests using turbo run test.
pnpm test:e2e	Executes end-to-end tests located in the e2e/ directory.
pnpm typecheck	Validates TypeScript types across the entire project.
pnpm clean	Removes node_modules and dist directories from all packages.

Sources: package.json:8-18

Development Cycle Diagram

The following sequence diagram describes the typical workflow for adding a new feature or agent adapter within the monorepo.

Skill Authoring and Structure

Individual skills within the monorepo (or created via the CLI) follow a specific file structure to ensure compatibility with the packages/core parser.

Standard Skill Layout

A skill directory typically contains:

• SKILL.md: The primary instruction and metadata file (Required).
• references/: Optional directory for supplemental documentation.
• scripts/: Optional directory for executable scripts used by the skill.
• assets/: Optional directory for static files or images.

Sources: packages/cli/src/commands/create.ts:50-75

Skill Parsing Flow

Summary

The SkillKit monorepo structure is designed for extensibility and consistency. By centralizing logic in packages/core and using Turbo for orchestration, the project maintains high performance in a multi-package environment. This architecture enables the primary goal of the project: creating portable, reusable AI instructions that function across 17 different coding agents.

Sources: README.md:12-18, package.json:1-5