Skills are modular, self-contained capability packages that extend AI Agent capabilities by providing specialized knowledge, workflows, and tools. They act as "onboarding guides" for specific domains or tasks, transforming a general-purpose AI Agent into an expert with specialized procedural knowledge.
What Skills Provide
1. Specialized Workflows: Automated multi-step procedures for specific domains.
2. Tool Integration: Instructions for handling specific file formats or APIs.
3. Domain Expertise: Company-specific knowledge, architecture, and business logic.
4. Bundled Resources: Scripts, references, and assets for complex and repetitive tasks.
Skill Structure
Each Skill consists of a required SKILL.md file and optional bundled resources. Skills should be created in the .codebuddy/skills/ directory within the workspace.
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter metadata (required)
│ │ ├── name: (required)
│ │ └── description: (required)
│ └── Markdown instructions (required)
└── Bundled Resources (optional)
├── scripts/ - Executable code (Python/Bash, etc.)
├── references/ - Documentation intended to be loaded into context as needed
└── assets/ - Files used in outputs (templates, icons, fonts, etc.)
SKILL.md (Required)
This is the core definition file for the Skill.
Metadata (YAML Frontmatter):
The name and description determine when the AI will use this Skill. The description should specifically explain what the Skill does and when it should be used.
Example:
---
name: pdf-editor
description: This skill should be used when users ask to modify, rotate, or extract text from PDF files.
allowed-tools: # Optional, specify allowed tools
disable: false # Optional, whether to disable
---
# PDF Editor
To rotate a PDF...
Bundled Resources (Optional)
1. Scripts (scripts/)
Executable code for tasks requiring deterministic reliability or that are repeatedly rewritten.
Use Case: When code is repeatedly rewritten or requires high reliability.
Example: scripts/rotate_pdf.py for PDF rotation.
2. References (references/)
Documentation and reference materials intended to be loaded into context as needed to assist AI reasoning.
Use Case: Database schemas, API documentation, domain knowledge, company policies, etc.
Advantage: Keeps SKILL.md concise, loading only when the AI determines it's needed.
3. Assets (assets/)
Files not intended to be loaded into context, but used in AI-generated outputs.
Use Case: Brand assets, PowerPoint templates, HTML/React boilerplate code, etc.
Progressive Disclosure Design Principle
Skills use a three-tier loading system to efficiently manage context:
1. Metadata: Always in context (~100 words).
2. Skill Body (SKILL.md body): Loaded when the Skill is triggered (<5k words).
3. Bundled Resources: Loaded by AI on demand (unlimited).
Skill Creation Process
1. Understand Requirements: Clarify the Skill's use cases and trigger conditions.
2. Plan Resources: Analyze whether scripts, reference documentation, or asset templates are needed.
3. Create Directory: Create a new Skill directory under .codebuddy/skills/.
4. Write SKILL.md:
Fill in YAML metadata.
Write Markdown instructions. Use imperative language (e.g., "To accomplish X, do Y").
Reference bundled resources.
Best Practices
Specific and Clear Description: Clearly state in description when the Skill should be used.
Imperative Language: Use verb-leading instructions in SKILL.md, rather than second person.
Load on Demand: Place lengthy documentation in references/ to avoid bloating SKILL.md.
Avoid Duplication: Information should exist in either SKILL.md or reference files, not both.
Skill Management
CodeBuddy provides a visual interface in the settings page to help you manage Skills.
In the settings management page, you can:
Centralized Management: View and manage all Skills at the project level (Project Skills) and user level (User Skills).
Import Skill: Click the "Import Skill" button in the upper right corner to import Skills you've obtained from the web.