Skills are modular, self-contained capability packages that extend the capabilities of AI Agents by providing specialized knowledge, workflows, and tools. They function like "onboarding guides" for specific domains or tasks, transforming general-purpose AI Agents into experts with specialized procedural knowledge.
What Can 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. Packaged resources: scripts, reference materials, and assets for complex and repetitive tasks.
Structure of a Skill
Each Skill consists of a required SKILL.md file and optional packaged resources. Skills should be created in the .codebuddy/skills/ directory of 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)
├── references/ - Documents intended to be loaded into context as needed
└── assets/ - Files used in output (templates, icons, fonts, etc.)
SKILL.md (Required)
This is the core definition file of a Skill.
Metadata (YAML Frontmatter):
name and description determine when the AI will use this Skill. The description should specify the Skill's features and use cases.
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. Specifies the tools that are allowed to be used.
disable: false # Optional. Whether to disable it.
---
# PDF Editor
To rotate a PDF...
Packaging Resources (Optional)
1. Scripts (scripts/)
Executable code for tasks that require determinism and reliability or are repeatedly rewritten.
Purpose: When code is repeatedly rewritten or high reliability is required.
Example: scripts/rotate_pdf.py is used for PDF rotation.
2. References (references/)
Documents and reference materials intended to be loaded into context as needed to assist AI reasoning.
Purpose: Database schemas, API documentation, domain knowledge, company policies, and more.
Advantage: Keeps SKILL.md concise and loads it only when the AI determines it is needed.
3. Assets (assets/)
Files that are not intended to be loaded into context, but rather used in AI-generated output.
Purpose: Brand assets, PPT templates, HTML/React boilerplate code, and more.
Progressive Disclosure Design Principles
Skills uses a three-level 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).
Process of Creating a Skill
1. Understand the requirement: Clarify the use cases and trigger conditions of the Skill.
2. Plan resources: Analyze whether scripts, reference documents, or asset templates are needed.
3. Create a directory: Create a new Skill directory under .codebuddy/skills/.
4. Write SKILL.md:
Fill in the YAML metadata.
Write the Markdown instructions. Use directive language (for example, "To accomplish X, do Y").
Reference the packaged resources.
Tips
Specific and clear description: Clearly explain in the description when the Skill should be used.
Directive language: Use verb-first instructions in SKILL.md instead of second-person phrasing.
Load on demand: Place long documents in references/ to prevent SKILL.md from becoming too bloated.
Avoid duplication: Information should exist in either SKILL.md or the referenced files, not in both places.
Skill Management
CodeBuddy provides a visual interface on the Settings page to help you manage Skills.
On the Settings management page, you can:
Centralized management: View and manage all Skills at the current 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 obtained from the internet.