Skills Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Skills Architecture in the code-cli project provides a modular framework for extending the AI agent's capabilities through specialized instruction packages. Skills act as "on-demand" instruction sets—similar to project-level AGENTS.md files—that provide workflows, guides, and best practices for specific tasks such as code reviewing, test generation, or changelog creation.
The architecture supports a multi-tiered discovery system where skills can be loaded from user-global directories, project-specific directories, or downloaded from a community marketplace. This allows the agent to adapt its reasoning and tool usage based on the specific requirements of the current workspace and the active skill set.
Sources: src/skills/types.ts:7-12, src/skills/SkillsRegistry.ts:25-30
Core Components
SkillsRegistry
The SkillsRegistry is the central manager for skill discovery, loading, and session-level activation. It maintains an internal map of all discovered skills and handles the logic for overriding skills when name collisions occur (where project-level skills typically take precedence over global ones).
Sources: src/skills/SkillsRegistry.ts:32-48, src/skills/types.ts:18-26
SkillParser
The SkillParser is responsible for converting raw SKILL.md files into structured SkillDefinition objects. It extracts YAML frontmatter delimited by --- and separates it from the Markdown body content.
Sources: src/skills/SkillParser.ts:16-45, src/skills/SkillParser.ts:86-118
ProjectAnalyzer
The ProjectAnalyzer provides automated skill discovery by scanning the project's root directory. It detects programming languages (TypeScript, Python, Rust, Go), frameworks (React, Next.js, Express, Flask), and patterns (testing, CLI, monorepo) to generate or suggest relevant skills.
Sources: src/skills/autoSkill.ts:134-200, src/skills/autoSkill.ts:210-280
Skill Data Model
Skills are defined using the SKILL.md format, which combines configuration (YAML) and instructions (Markdown).
Skill Definition Fields
| Field | Type | Description |
|---|---|---|
name | string | Required. Max 64 chars, lowercase alphanumeric and hyphens. |
description | string | Required. Max 1024 chars. Explains the skill's purpose. |
body | string | The Markdown instructions provided to the LLM. |
allowed-tools | string | Optional. Space-delimited list of tools the skill is authorized to use. |
source | SkillSource | Location where the skill was loaded from (e.g., autohand-project). |
isActive | boolean | Indicates if the skill instructions are currently injected into the agent context. |
Sources: src/skills/types.ts:39-75, src/skills/types.ts:105-115
Data Flow: Skill Loading and Activation
The following diagram illustrates how the system discovers and activates skills during an agent session.
The registry loads skills from multiple sources, with project-specific skills overriding global ones during the registration phase.
Sources: src/skills/SkillsRegistry.ts:150-180, src/skills/SkillsRegistry.ts:320-335
Skill Discovery and Generation
The architecture supports three methods for obtaining skills:
1. Manual Creation
Users can generate new skills via the /skills new command. This utilizes an LLM to generate the SKILL.md file based on a user-provided name and description, including YAML frontmatter and structured Markdown instructions.
Sources: src/commands/skills-new.ts:38-120
2. Auto-Generation
The runAutoSkillGeneration function analyzes the tech stack of a repository and invokes an LLM to create three high-quality, actionable skills tailored to the project (e.g., a "React Component Helper" for a Next.js project).
Sources: src/skills/autoSkill.ts:460-520, src/skills/autoSkill.ts:540-565
3. Community Installation
Skills can be searched and installed from a central GitHub registry using the /skills install command.
Sources: src/commands/skills-install.ts:45-75
Skill Storage and Hierarchy
Skills are loaded from multiple directories with a specific precedence order. This allows the platform to support skills originally created for other tools (like Claude or Codex) while maintaining its own native formats.
| Source Key | Path | Recurrence |
|---|---|---|
autohand-project | <cwd>/.autohand/skills/**/SKILL.md | Recursive |
autohand-user | ~/.autohand/skills/**/SKILL.md | Recursive |
claude-project | <cwd>/.claude/skills/*/SKILL.md | Single Level |
claude-user | ~/.claude/skills/*/SKILL.md | Single Level |
Sources: src/skills/types.ts:18-26, src/skills/SkillsRegistry.ts:150-165
Technical Implementation Details
Similarity Matching
The registry uses Jaccard similarity to find similar skills or prevent duplicates. This is calculated by tokenizing the skill name and description into sets of lowercase words and measuring their intersection over union.
Sources: src/skills/SkillsRegistry.ts:415-445
Skill Activation Logic
When a skill is activated, its body content is retrieved and appended to the agent's system prompt during the buildSystemPrompt phase in the core agent logic.
Sources: src/core/agent.ts:1320-1340, src/skills/SkillsRegistry.ts:380-385
Tool Constraints
Skills can define an allowed-tools field. While defined in the metadata, the agent uses this to restrict or prioritize specific tools when that skill's workflow is being followed.
Sources: src/skills/types.ts:49, src/skills/autoSkill.ts:480-490
Conclusion
The Skills Architecture provides a flexible and extensible way to guide AI behavior. By separating specialized instructions from the core agent logic and providing automated discovery tools, the system ensures the agent remains highly relevant to the specific codebase it is operating within.
Sources: src/skills/SkillsRegistry.ts:7-15, src/skills/autoSkill.ts:7-12