Translation Engine

Relevant source files

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

• packages/core/src/skill-translator.ts
• packages/core/src/translator/registry.ts
• packages/core/src/translator/types.ts
• packages/core/src/translator/formats/skill-md.ts
• packages/core/src/translator/formats/cursor.ts
• packages/cli/src/commands/translate.ts

The Translation Engine is the core component of SkillKit responsible for cross-agent compatibility. It enables the translation of AI agent skills between 17 different formats, allowing a single skill definition to be deployed across diverse AI coding assistants such as Claude Code, Cursor, Windsurf, and GitHub Copilot.

The engine works by parsing source files into a Canonical Skill representation—a standardized intermediary format—and then generating the specific syntax, file structure, and metadata required by the target agent. This process ensures that complex agent-specific features like glob patterns, tool restrictions, and auto-apply rules are either correctly mapped or appropriately flagged when incompatible.

Sources: packages/core/src/skill-translator.ts:1-10, packages/core/README.md

Core Architecture

The translation architecture is built on a registry-based provider model. A central registry manages various format-specific translators, each specializing in a particular category of AI agent instructions.

Translation Workflow

The following diagram illustrates the data flow from a source skill file to a target agent format.

The workflow ensures that the engine can handle bidirectional translations between any supported formats.
Sources: packages/core/src/translator/registry.ts:7-50, packages/core/src/skill-translator.ts:160-190

Format Categories

The engine categorizes agents into four primary format types to manage translation logic:

Category	Description	Primary Agents
skill-md	Standard Markdown with YAML frontmatter	Claude Code, Roo, Trae, Goose
cursor-mdc	MDC format with glob patterns	Cursor
markdown-rules	Plain Markdown or HTML-comment metadata	Windsurf, GitHub Copilot
external	Formats for external systems	Devin, etc.

Sources: packages/core/src/translator/types.ts:7-15, packages/core/src/translator/types.ts:20-40

Canonical Skill Representation

The CanonicalSkill interface serves as the universal intermediary. When a skill is parsed, its metadata and body are mapped to this structure before being re-encoded for the target.

export interface CanonicalSkill {
  name: string;
  description: string;
  version?: string;
  author?: string;
  tags?: string[];
  content: string; // The main Markdown instructions
  sourceFormat: FormatCategory;
  globs?: string[]; // Specifically for Cursor/MDC
  alwaysApply?: boolean;
  allowedTools?: string;
  agentHints?: {
    optimized?: string[];
    compatible?: string[];
  };
}

Sources: packages/core/src/translator/types.ts:71-104, packages/core/src/skill-translator.ts:44-59

Format Translators

Each format category is handled by a class implementing the FormatTranslator interface. These translators are responsible for three main tasks: Detection, Parsing, and Generation.

SkillMdTranslator (skill-md)

This is the default format used by the majority of supported agents (13 out of 17). It utilizes YAML frontmatter to store metadata.

• Detection: Looks for SKILL.md filenames or YAML frontmatter containing name or description fields.
• Generation: Produces a standardized Markdown file with a --- fenced YAML block.

Sources: packages/core/src/translator/formats/skill-md.ts:50-120

CursorTranslator (cursor-mdc)

Handles Cursor's specific .mdc format, which emphasizes automatic rule application based on file patterns.

• Glob Inference: If a source skill lacks glob patterns, the translator automatically infers them based on tags (e.g., the react tag generates **/*.tsx and **/*.jsx).
• Always Apply: Maps the alwaysApply boolean to Cursor's rule-triggering logic.

Sources: packages/core/src/translator/formats/cursor.ts:32-70, packages/core/src/translator/formats/cursor.ts:149-170

Windsurf & Copilot Translators (markdown-rules)

These agents often use specific filenames (e.g., .windsurfrules or copilot-instructions.md) and may store metadata in HTML comments to keep the file valid Markdown for the agent's parser.
Sources: packages/core/src/translator/tests/windsurf.test.ts:32-50, packages/core/src/translator/tests/copilot.test.ts:12-30

Technical Implementation Details

Metadata Handling and Compatibility

During translation, the engine tracks features that may not be supported by the target agent.

Configuration Generation

Beyond individual skill files, the engine generates master configuration files that instruct agents on how to invoke the skills.

Format	Output Type	Target Agents
xml	<skills_system> block	Claude Code, Roo
mdc	Markdown with YAML & XML data	Cursor
markdown-table	MD Table with invoke commands	Codex
json	JSON code block in Markdown	Gemini CLI
markdown	H3 Sections with Invoke strings	Windsurf, Trae, Copilot

Sources: packages/core/src/skill-translator.ts:365-450

CLI Integration

The translation engine is exposed via the skillkit translate command. It supports single-file translation, project-wide bulk translation, and dry-run previews.

• Path Selection: The CLI automatically resolves output paths based on agent-specific defaults (e.g., .cursor/rules/ for Cursor).
• Force Overwrite: Prevents accidental data loss unless the --force flag is provided.
• Metadata Injection: Optional --metadata flag adds _translated-from and _translated-at fields to the generated frontmatter.

Sources: packages/cli/src/commands/translate.ts:20-80, packages/cli/src/commands/translate.ts:182-220

Summary

The Translation Engine provides a robust abstraction layer for AI agent instructions. By utilizing a canonical intermediary and specialized format providers, it solves the problem of "agent lock-in," allowing developers to maintain a single source of truth for their development methodologies while supporting the specific requirements of every major AI coding assistant.