Skills ​

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:

markdown
---
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.