Supported Agents & Adapters
Relevant source files
The following files were used as context for generating this wiki page:
SkillKit provides a robust architecture for integrating with various AI coding agents through a system of adapters and translators. This system allows "skills"—portable instruction files—to be shared, translated, and synchronized across 17 different AI coding environments, including Claude Code, Cursor, Windsurf, and GitHub Copilot.
The primary goal of the adapter layer is to abstract the specific directory structures, configuration formats, and invocation commands of each agent. By providing a canonical representation of agents and skills, SkillKit ensures that a single skill definition can be automatically converted into the native format required by any supported target agent.
Sources: packages/agents/README.md:1-10, packages/core/src/skill-translator.ts:1-10, README.md:10-25
Agent Adapter Architecture
The @skillkit/agents package defines the standard interface for agent adapters. Each adapter contains the logic necessary to detect an agent's presence on a user's system and generate the specific configuration files needed to register skills with that agent.
Adapter Interface Definition
Every supported agent must implement a standard AgentAdapter interface. This ensures consistency in how the CLI and core libraries interact with different AI tools.
interface AgentAdapter {
name: AgentType; // Agent identifier (e.g., 'claude-code')
displayName: string; // Human-readable name
format: 'skill-md' | 'mdc' | 'markdown';
skillsDir: string; // Relative project skills directory
globalSkillsDir: string; // Global skills directory (supports ~)
configFile: string; // Configuration file name (e.g., 'CLAUDE.md')
generateConfig(skills: Skill[]): string; // Logic to build config content
parseConfig(content: string): Skill[]; // Logic to read existing config
}
Sources: packages/agents/README.md:112-140, packages/agents/src/tests/clawdbot.test.ts:25-50
Discovery and Detection
The system uses specific file system indicators to detect which agents are active in a project or globally on a user's machine. This is handled by detectAgent() and detectAllAgents() functions which look for specific directories like .claude/, .cursor/, or global paths in the user's home directory.
The logic for specific adapters, such as Clawdbot, checks for multiple indicators including workspace directories (skills/), global directories (~/.clawdbot), and specific JSON config files (clawdbot.json).
Sources: packages/agents/README.md:65-80, packages/agents/src/tests/clawdbot.test.ts:210-250
Supported Agents Registry
SkillKit supports 17 distinct AI coding agents. Each agent is categorized by its preferred configuration format and default directory structure.
| Agent | Config Format | Skills Directory | Config File |
|---|---|---|---|
| Claude Code | XML (in MD) | .claude/skills/ | CLAUDE.md |
| Cursor | MDC (.mdc) | .cursor/skills/ | .cursor/rules/skills.mdc |
| Windsurf | Markdown | .windsurf/skills/ | .windsurf/rules/skills.md |
| GitHub Copilot | Markdown | .github/skills/ | .github/copilot-instructions.md |
| Roo Code | XML | .roo/skills/ | ROO.md |
| Gemini CLI | JSON | .gemini/skills/ | GEMINI.json |
| Codex | MD Table | .codex/skills/ | CODEX.md |
Sources: packages/agents/README.md:15-35, packages/core/src/skill-translator.ts:60-75, packages/core/src/skill-translator.ts:500-550
Skill Translation & Format Adapters
To enable cross-agent portability, SkillKit converts skills into a CrossAgentSkill canonical format before translating them to the target agent's specific requirements.
Translation Logic Flow
The translateSkillToAgent function manages the conversion process, handling agent-specific fields such as "hooks" (supported in Claude Code) or "globs" (supported in Cursor).
Format-Specific Generation
The system generates different file structures based on the target agent's configFormat property:
- XML: Used by Claude Code and Roo; wraps skill definitions in
<skills_system>and<available_skills>tags. - MDC: Used by Cursor; includes frontmatter with
globsandalwaysApplysettings. - Markdown Table: Used by Codex to provide a readable overview of commands.
- JSON: Used by Gemini CLI for structured capability definitions.
Sources: packages/core/src/skill-translator.ts:460-500, packages/core/src/skill-translator.ts:555-580
Agent Persona Management
Beyond standard skills, SkillKit supports "Custom AI Sub-Agents"—specialized personas like "architect" or "security-reviewer" that can be managed via the skillkit agent command.
Agent Definition Structure
Custom agents are defined as Markdown files with YAML frontmatter, similar to skills, but focus on system prompts and tool permissions.
---
name: architect
description: Technical lead persona
model: opus
permissionMode: default
allowed-tools: [Read, Write, Bash]
---
# Architect Persona
You are a senior software architect responsible for system design...
Sources: packages/core/src/agents/parser.ts:40-100, packages/cli/src/commands/agent.ts:540-570
Agent Translation & Compatibility
When translating agent personas between formats (e.g., from Claude to Cursor), SkillKit tracks "incompatible" features. For example, hooks and permissionMode are flagged as incompatible when moving to the universal agent format.
if (targetFormat === 'universal') {
if (canonical.hooks && canonical.hooks.length > 0) {
incompatible.push('hooks (not supported in universal format)');
}
if (canonical.permissionMode) {
incompatible.push('permissionMode (not supported in universal format)');
}
}
Sources: packages/core/src/agents/translator.ts:40-60, packages/core/src/agents/translator.ts:310-335
CLI Agent Operations
The AgentCommand class provides the user interface for managing these adapters and personas through the terminal.
Key Commands
- agent list: Discovers and displays all project and global agents.
- agent create: Scaffolds a new agent definition using a standard template.
- agent sync: Bulk translates and writes agent definitions to the appropriate hidden directories (e.g.,
.claude/agents/). - agent validate: Checks agent Markdown files against the required schema (name format, frontmatter presence, description length).
Sources: packages/cli/src/commands/agent.ts:15-100, packages/cli/src/commands/agent.ts:450-480, packages/core/src/agents/parser.ts:250-300
Conclusion
The Adapter and Agent system in SkillKit acts as the translation layer between generic, reusable developer knowledge (Skills) and the specific execution environments of modern AI coding assistants. By centralizing agent configurations and providing automated format translation, SkillKit removes the friction of switching between tools and ensures that specialized AI instructions remain portable and maintainable across the entire development ecosystem.