Writing Custom Skills
Relevant source files
The following files were used as context for generating this wiki page:
Custom skills in the plugsuits ecosystem provide specialized instructions and workflow guidance for AI agents. They are designed to encapsulate complex procedures, such as git workflows or code refactoring patterns, into loadable modules that the agent can retrieve and follow using the load_skill tool.
The system supports multiple skill formats, including a directory-based "v2" standard that allows for subdirectories, scripts, and reference documentation. Skills are discovered from bundled, global, and project-specific directories, allowing developers to share common workflows or define project-local automations. Sources: packages/harness/src/skills.ts:245-255, packages/cea/src/skills/example/SKILL.md
Skill Discovery and Architecture
The SkillsEngine is responsible for scanning the filesystem to identify available skills. It looks for Markdown files or specific directory structures across five potential locations: bundled internal skills, global user skills, global commands, project-local skills, and project-local commands. Sources: packages/harness/src/skills.ts:257-269, packages/cea/src/context/skills.ts:8-14
Skill Formats
There are three primary formats recognized by the engine:
| Format | Description | File Structure |
|---|---|---|
legacy | A single standalone Markdown file with basic frontmatter. | skill-name.md |
v2 | A directory-based skill supporting sub-resources like scripts. | skill-name/SKILL.md |
command | A specialized format for slash commands. | command-name.md |
Sources: packages/harness/src/skills.ts:16-29, packages/harness/src/skills.ts:182-184
Discovery Flow
The following diagram illustrates how the SkillsEngine resolves skill IDs to local paths:
Writing a v2 Skill
The v2 format is the recommended standard for complex workflows. It requires a directory named after the skill, containing a SKILL.md file as the entry point. This entry point must include YAML frontmatter. Sources: packages/harness/src/skills.ts:182-200, packages/cea/src/skills/example/SKILL.md:1-10
Frontmatter Configuration
The frontmatter defines the metadata and triggers for the skill.
---
name: example
description: A description of what this skill does
version: 1.0.0
triggers:
- "keyword to trigger"
allowed-tools:
- "shell_execute(*)"
---
Sources: packages/harness/src/skills.ts:36-49, packages/cea/src/skills/git-workflow.md:1-15
Directory Structure
A v2 skill can organize secondary files in subdirectories, which are accessible via the load_skill tool by providing a relative path.
SKILL.md(Required): Metadata and primary instructions.scripts/: Executable scripts (e.g.,setup.sh).references/: Supplementary documentation.
Sources: packages/cea/src/skills/example/SKILL.md:15-30, packages/cea/src/tools/planning/load-skill.ts:40-45
Loading and Integration
The load_skill tool is the interface for agents to access skill content. It validates the skill name and, for v2 skills, ensures that any requested relative path remains within the skill's directory to prevent path traversal attacks. Sources: packages/cea/src/tools/planning/load-skill.ts:28-38, packages/cea/src/tools/planning/load-skill.ts:100-110
Execution Sequence
The sequence below shows how an agent retrieves a specific file from a v2 skill:
Tool Schema
The load_skill tool accepts the following parameters:
| Parameter | Type | Description |
|---|---|---|
skillName | string | The ID of the skill (e.g., 'git-workflow'). |
relativePath | string | (Optional) Path to a file within a v2 skill directory. |
Sources: packages/cea/src/tools/planning/load-skill.ts:14-25
Best Practices for Skill Content
Based on the git-workflow implementation, effective skills should include:
- Triggers: Explicit phrases that signal when the agent should load the skill. Sources: packages/cea/src/skills/git-workflow.md:4-14
- Core Responsibilities: A bulleted list of what the skill covers. Sources: packages/cea/src/skills/git-workflow.md:21-26
- Safety Guardrails: Clear instructions on which commands are safe versus dangerous. Sources: packages/cea/src/skills/git-workflow.md:45-60
- Workflow Patterns: Step-by-step shell command examples. Sources: packages/cea/src/skills/git-workflow.md:64-90
- Integration Notes: Descriptions of how the skill interacts with other tools like
shell_execute. Sources: packages/cea/src/skills/git-workflow.md:250-255
Conclusion
Custom skills are a powerful mechanism for extending agent capabilities without modifying the core engine. By adhering to the v2 directory standard and providing structured frontmatter, developers can create portable, safe, and highly specific workflow guides that ensure the agent operates according to project-specific standards.