tencent cloud

Skills Features

Download
Focus Mode
Font Size
Last updated: 2026-09-30 18:41:45
AI-Translated

Overview

Skills is an extension capability system of CodeBuddy Code that allows you to create specialized domain knowledge and workflow templates, enabling AI assistants to handle specific types of tasks more professionally.

What Are Skills

Skills are similar to "professional training" provided for AI assistants. With Skills, you can:
Encapsulate professional knowledge: Encapsulate best practices and operational workflows from specific domains into reusable skills.
Provide workflow templates: Define standardized task processing workflows to improve work efficiency.
Extend AI capabilities: Enable AI assistants to handle more specialized and complex tasks.
Team collaboration and sharing: Project-level Skills enable professional knowledge to be shared among team members.

Skills vs Slash Commands

Feature
Skills
Slash Commands
Trigger Method
The AI model automatically identifies and invokes.
The user manually enters a command.
Application Scenario
Professional domain task processing
Quick operations and workflows
Permission Control
Supports tool allowlist restrictions.
No special permission control
Working Directory
Supports custom base directory.
Use the current working directory.
Visibility
Transparent to users, with automatic AI decision-making.
User-initiated
In short:
Slash Commands are shortcuts that users invoke proactively.
Skills are specialized capabilities that AI automatically selects based on task requirements.

Creating Skills

Directory Structure

Skills are defined by creating a SKILL.md file in a specific directory:
1. Project-level Skills: .codebuddy/skills/ (under the project root directory)
2. User-level Skills: ~/.codebuddy/skills/ (under the user home directory)
Each Skill is a standalone directory that contains a SKILL.md file:
.codebuddy/skills/
├── pdf/
│ └── SKILL.md
├── data-analysis/
│ └── SKILL.md
└── code-review/
└── SKILL.md

SKILL.md Format

Skill files use Markdown format and support YAML Frontmatter for defining metadata:
---
name: pdf
description: PDF document processing expert
allowed-tools: Read, Write, Bash, WebFetch
---

You are a PDF document processing expert, skilled in:
- Parse and extract PDF content
- Convert PDF to other formats
- Generate a PDF report

Use the following workflow when users need to handle PDF-related tasks:
1. First, check whether the PDF file exists.
2. Use an appropriate tool to extract content.
3. Process it as needed.
4. Generate a result report.

Available tools:
- pdftotext: Extract text content.
- pdfinfo: Obtain PDF information.

Frontmatter Fields

Field
Required
Description
Example
name
No
Skill name. If not specified, the directory name is used.
pdf
description
No
Skill description that helps AI understand when to use it.
PDF document processing expert (project)
allowed-tools
No
Allowlist of tools that can be used, separated by commas
Read, Write, Bash
disable-model-invocation
No
When set to true, the Skill does not appear in the Skill tool and can only be triggered manually through /skill-name.
true
user-invocable
No
When set to false, the Skill is hidden from the / menu and is only available for internal AI invocation or reference by other Skills. The default value is true.
false
context
No
When set to fork, the Skill runs in an independent subagent context.
fork
agent
No
Specifies the subagent type. This is valid only when context: fork is set.
Explore
model
No
Model used when the Skill runs. This takes effect only when context: fork is set. If not configured, the default model of the agent is used.
claude-sonnet-4
hooks
No
Declares Skill-specific Hooks in SKILL.md. This takes effect only when context: fork is set. For details, see Configuring Hooks in a Skill.
See below

Variable Placeholders

SKILL.md content supports the following placeholders, which are automatically replaced when the SKILL.md content is loaded or executed. The same placeholders also apply to custom slash commands and subagent definitions.
Placeholder
Replace With
Applicable Source
${CODEBUDDY_PLUGIN_ROOT}
Plugin installation root directory
Skills from plugin sources only
${CODEBUDDY_SKILL_DIR}
Absolute path of the directory containing the current SKILL.md
All sources
${CODEBUDDY_SESSION_ID}
Current session ID (injected at runtime)
All sources
Uppercase environment variables such as ${MY_ENV_VAR}
Value of process.env.MY_ENV_VAR
All sources
${MY_ENV_VAR:-default value}
Environment variable. The default value is used when it is missing.
All sources
To maintain compatibility with Claude Code, ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_SKILL_DIR}, and ${CLAUDE_SESSION_ID} are also recognized as equivalent aliases.
Placeholders for unset environment variables are retained as-is and are not replaced with empty strings. In skills from user or project sources, ${CODEBUDDY_PLUGIN_ROOT} is retained literally because this variable applies only to plugin sources.
Example:
---
description: A sample skill with placeholders
---

Read the script @${CODEBUDDY_SKILL_DIR}/scripts/analyze.py and execute it with the key ${MY_API_TOKEN:-dev-fallback}.
Current session ID: ${CODEBUDDY_SESSION_ID}

Executing Shell Commands

Like slash commands, Skills also support inline execution of Shell commands in SKILL.md using the !command`` syntax. When a Skill is triggered, whether automatically by the AI or manually by the user through /skill-name, these commands are executed and their output is substituted into the Skill content for subsequent analysis by the AI.
Example:
---
description: Project status analysis
---

### Current working directory

!`echo "CWD=$(pwd)"`

### Git status

!`git status --short`

### Recent Commits

!`git log --oneline -5`

Based on the information above, analyze the current status of the project.

Supported Features

$ARGUMENTS Parameter substitution: Before a Shell command is executed, $ARGUMENTS is replaced with the parameters passed by the user.
@file File reference: After a Shell command is executed, @file references are processed based on size and token limits. Small files are injected directly, longer content is truncated with a prompt to continue reading, and oversized files retain the original reference.
Error isolation: A failure in one command does not affect other commands, and the failed command is replaced with an empty string.
Processing pipeline: $ARGUMENTS substitution → !command`` execution → @file reference processing, consistent with the processing order of slash commands.

Context Fork

context: fork runs the Skill in an isolated subagent context without access to the conversation history.
---
name: deep-research
description: Conduct in-depth research on a topic
context: fork
agent: Explore
---

Research $ARGUMENTS:
1. Use Glob and Grep to find relevant files
2. Read and analyze the code.
3. Summarize the findings and attach specific file references.

Available Agent Types

Type
Description
general-purpose
General (default)
Explore
Read-only tool for optimizing codebase exploration
Plan
Planning and analysis
Custom
agent defined in .codebuddy/agents/

Hiding a Skill (user-invocable)

user-invocable: false hides the Skill from the / menu. This is applicable when:
Background knowledge Skills, such as project specifications and coding standards.
Auxiliary Skills intended only for internal reference by other Skills or the AI.
---
name: project-guidelines
description: Project coding standards and best practices.
user-invocable: false
---

# Project Coding Standards

This project adheres to the following coding standards:
- Use TypeScript strict mode.
- Use camelCase for function names.
- Use PascalCase for component names.
...
These Skills are loaded into the AI's context, but users cannot invoke them directly from the / menu.

Execution Flow

1. Create a new isolated context.
2. The subagent receives the Skill content as a prompt.
3. The agent field determines the execution environment.
4. The results are returned to the main conversation.
Note:
context: fork is only applicable to Skills that contain explicit tasks. When there are only guidelines without specific tasks, no meaningful output is produced.

Configuring Hooks in a Skill

Version requirements: The Skill frontmatter hooks field requires a version of CodeBuddy Code that supports Frontmatter Hooks (Beta).
In addition to configuring Hooks globally in ~/.codebuddy/settings.json, a Skill can also declare the hooks field directly in the frontmatter of SKILL.md, packaging the Hook together with the Skill itself. This is especially useful for fork-type Skills—you can add guards, logging, and callbacks inside the fork subagent without polluting the main session.

Applicable Scope

Only context: fork takes effect: Skills on the injection path (default inline mode) do not have clear lifecycle boundaries, so frontmatter hooks are parsed but not registered with the runtime.
The lifecycle is bound to the fork subagent: hooks are registered when the fork subagent starts and automatically cleaned up when it ends, without affecting the main session or other Skills.
Stop is automatically converted to SubagentStop: Writing a Stop event in the frontmatter is automatically rewritten to SubagentStop, aligning with the actual event when the subagent completes.

Field Format

The structure of the hooks field is exactly the same as the hooks in settings.json—grouped by event name, with each configuration optionally containing a matcher and a hooks[] array:
---
name: secure-reviewer
description: Code review Skill that checks the file allowlist before execution.
context: fork
agent: Explore
hooks:
PreToolUse:
- matcher: "Read|Glob|Grep"
hooks:
- type: command
command: ${CODEBUDDY_SKILL_DIR}/scripts/check-paths.sh
timeout: 10
PostToolUse:
- matcher: "Bash"
hooks:
- type: prompt
prompt: "Check whether the Bash output contains sensitive information. If found, explain it in the reason field."
Stop: # Automatically rewritten to SubagentStop
- hooks:
- type: command
command: echo "review skill finished" >> ${CODEBUDDY_PROJECT_DIR}/.cbc-review.log
---

Please review the files mentioned in $ARGUMENTS...
Supported hook types:
command: Executes a shell command (with optional fields such as shell: bash | powershell, timeout, if, once, and async).
prompt: Passed to a small model (Haiku-tier by default) for semantic determination.
agent: Spawns a subagent for more complex determinations, with optional agentType / model parameters.
http: Sends the event payload to a specified URL via POST/PUT/PATCH.
For complete field semantics, see the Hook Reference Guide.

Security Gate: admin-trusted

For security reasons, Skill frontmatter hooks from non-built-in sources are not registered by default. All Skills loaded from .codebuddy/skills/, local projects, or the plugin marketplace are considered untrusted sources because they can silently trigger Shell commands, so explicit user consent is required.
To enable: Configure it in ~/.codebuddy/settings.json.
{
"allowUntrustedFrontmatterHooks": true
}
Only after this is enabled will Skill / Agent frontmatter hooks from all sources be registered. Otherwise, the CLI outputs a warning similar to the following and skips the hooks of that Skill:
[AgentTask] Frontmatter hooks from skill 'secure-reviewer' skipped
(source not admin-trusted; enable `allowUntrustedFrontmatterHooks` in settings to allow)
Built-in product-bundled Skills are not subject to this gate and are automatically allowed. hooks configured by plugins through hooks/hooks.json take a different path and are not controlled by this gate.

Merging with Global hooks

Skill frontmatter hooks and global hooks in settings.json are merged additively—all matching hooks from both sides under the same event are triggered in parallel, with no overriding. The differences are as follows:
Source
Scope
Constrained by admin-trusted Gate or Not
settings.json (global/project/local)
Entire session
No
Plugin hooks/hooks.json
Entire session (when the plugin is enabled)
No
Agent .md frontmatter
Lifecycle of the subagent
Yes
Skill SKILL.md frontmatter (fork only)
Lifecycle of the fork subagent
Yes

Debugging

Set CODEBUDDY_DEBUG=1 at startup to see registration lines such as [ScopedHookRegistry] registered N hook config(s) for scope ... in the logs.
Invalid hook definitions in frontmatter are silently discarded, but a log entry is output: [parseFrontmatterHooks] skill 'xxx': event 'YYY' invalid: .... Check the logs carefully to locate the issue.

Usage Examples

Example 1: PDF Processing Skill

File: .codebuddy/skills/pdf/SKILL.md
---
name: pdf
description: PDF document processing and conversion expert
allowed-tools: Read, Write, Bash, WebFetch
---

# PDF Processing Expert

You are a professional PDF document processing expert.

## Core Capabilities
- Extract text content from PDF.
- Convert PDF to Markdown, HTML, and other formats.
- Merge and split PDF files.
- Extract PDF metadata and bookmarks.

## Workflow
1. Check whether the PDF file exists and is accessible.
2. Use pdftotext or pdfinfo to obtain basic information.
3. Select an appropriate processing tool based on the task type.
4. Verify the integrity of the output results.

## Available Tools
- pdftotext: Extract plain text.
- pdfinfo: Obtain document information.
- pdftk: Merge and split operations.
Usage: When a user asks "Help me extract the content of this PDF", the AI automatically recognizes the need for PDF processing capabilities and invokes the Skill.

Example 2: Data Analysis Skill

File: ~/.codebuddy/skills/data-analysis/SKILL.md
---
name: data-analysis
description: Data analysis and visualization expert
allowed-tools: Read, Write, Bash, WebFetch, NotebookEdit
---

# Data Analysis Expert

You are a professional data analyst, skilled in using Python and related tools for data analysis.

## Core Capabilities
- Data cleaning and preprocessing
- Statistical analysis and modeling
- Data visualization
- Generate an analysis report

## Analysis Workflow
1. Understand the data structure and quality
2. Clean and preprocess data
3. Perform statistical analysis
4. Create visualizations
5. Generate analysis conclusions

## Tool Library
- pandas: data processing
- numpy: numerical computing
- matplotlib/seaborn: visualization
- scikit-learn: machine learning

## Best Practices
- Always explore data quality first
- Use Jupyter Notebook for interactive analysis
- Save intermediate results to avoid repeated computation

Example 3: Code Review Skill

File: .codebuddy/skills/code-review/SKILL.md
---
name: code-review
description: Code review and quality inspection expert
allowed-tools: Read, Grep, Bash, Edit
---

# Code Review Expert

You are an experienced code reviewer who follows industry best practices.

## Review Focus
1. **Code Quality**
- Naming Conventions
- Code Complexity
- Duplicate Code

2. **Security**
- SQL Injection Risks
- XSS Vulnerabilities
- Authentication and Authorization Issues

3. **Performance**
- Algorithm Efficiency
- Resource Usage
- Caching Policy

4. **Maintainability**
- Code Comments
- Modular Design
- Test Coverage

## Review Process
1. Understand the purpose of the code changes.
2. Check code style and standards.
3. Analyze potential bugs and performance issues.
4. Verify security.
5. Provide constructive suggestions for improvement.

## Output Format
- Strengths: List what was done well.
- Issues: Point out areas that need improvement.
- Suggestions: Provide specific improvement plans.

How AI Selects Skills

The AI decides whether to invoke a Skill based on the following factors:
1. Task relevance: The correlation between the task description and the Skill description.
2. Tool requirements: Whether the tools required by the task are within the allowed-tools scope.
3. Context relevance: Whether the current conversation context is suitable for using this Skill.
4. Skill source: Project-level Skills take precedence over user-level Skills.

Overriding Skill Visibility via Settings (skillOverrides)

The skillOverrides setting allows you to control the visibility of individual Skills from settings without modifying SKILL.md, which is useful for Skills that are inconvenient to modify, such as project Skills committed to a shared repository.
The configuration is located in skillOverrides in settings, indexed by Skill name, with each value being one of four states:
Value
Visible to Model
In / Menu
Description
on
Name + Description
Yes
Does not override and falls back to the current SKILL.md frontmatter state.
name-only
Name only
Yes
Collapse the description to save context budget.
user-invocable-only
Hidden
Yes
Hidden from the model (not included in the list), but calls by name from users and the model are still allowed.
off
Hidden
Hidden
Hidden from both the model and the menu, and calling by name returns a disabled prompt.
The /skills menu labels the user-invocable-only state as user-only. This is only a short label for display, and the canonical value written to the configuration file remains user-invocable-only.
Skills not listed are treated as on. Example:
{
"skillOverrides": {
"legacy-context": "name-only",
"deploy": "off"
}
}
After it is set to off, both /skill-name and model invocations by name will be intercepted with a prompt:
Skill "<name>" is disabled via skillOverrides. Re-enable it in /skills or remove the override from your settings to run it.
Key Points:
plugin Skills are not affected by skillOverrides. Instead, they are managed through /plugin and appear as locked (locked by plugin) in /skills, where they cannot be edited.
/skills menu visual editing: Use ↑/↓ to select, enter / space / ←/→ to cycle through states. When you press Esc, all changes are written to .codebuddy/settings.local.json and the number of changes is reported (Updated N skill override / No changes). If you leave without pressing Esc, changes are not saved.
Precedence: PROJECT_LOCAL (.codebuddy/settings.local.json) > PROJECT (.codebuddy/settings.json) > USER (~/.codebuddy/settings.json). Higher-priority settings override lower-priority ones by Skill name. When the workspace root is the home directory, PROJECT and USER refer to the same file.
Invalid values fall back automatically: Before merging, invalid values that do not belong to the four states are filtered out, so invalid values in higher-priority files do not mask valid values in lower-priority files (falling back to the previous valid file). If all values are invalid, the Skill is treated as on.

Permission Control

allowed-tools Allowlist

Use the allowed-tools field to limit the tools available to a Skill:
allowed-tools: Read, Write, Bash(git:*), Grep
Supported tool pattern matching:
Bash(git:*) - Only git-related commands are allowed.
Edit(src/**/*.ts) - Only editing files in specific paths is allowed.

Working Directory Restrictions

Each Skill has its own baseDirectory (the directory containing SKILL.md), which can be referenced in Skill instructions:
When processing files, search for related resources in the {baseDirectory} directory first.

Best Practices

1. Clear Skill Descriptions

# ✖ Not recommended
description: Process files

# ✔ Recommended
description: PDF document parsing and conversion expert, supporting text extraction and format conversion (project)

2. Detailed Instructions

Provide detailed:
Core Capabilities Description
Standard Workflow
Available Tools List
Common Scenario Handling Methods
Output Format Requirements

3. Appropriate Tool Permissions

Grant only the necessary tool permissions:
# ✖ Excessive permissions
allowed-tools: Bash

# ✔ Precise control
allowed-tools: Read, Write, Bash(git:status,git:diff), Grep

4. Organizing Skill Directories

Organize Skills by functional area:
.codebuddy/skills/
├── document/
│ ├── pdf/SKILL.md
│ └── markdown/SKILL.md
├── data/
│ ├── analysis/SKILL.md
│ └── visualization/SKILL.md
└── code/
├── review/SKILL.md
└── refactor/SKILL.md

Debugging Skills

Viewing Loaded Skills

Use the /skills command to view all currently loaded Skills:
/skills
The Skills panel displays:
User skills: user-level Skills (~/.codebuddy/skills/)
Project skills: project-level Skills (.codebuddy/skills/)
Plugin skills: Skills provided by plugins
Each Skill displays its name and the estimated number of tokens.

FAQs

Q: Was the Skill not triggered?
Check whether the description clearly describes the Skill's functionality.
Confirm that the task description matches the Skill's capabilities.
Verify whether allowed-tools includes the required tools.
Q: Does the Skill have insufficient permissions?
Check the allowed-tools configuration.
Confirm that the tool name is spelled correctly.
Use pattern matching to precisely control permissions.
Q: Do project-level and user-level Skills conflict?
Project-level Skills have a higher priority.
Use different names to avoid conflicts.

Integration with Other Features

Skills + Memory

Skills can access information stored in the Memory system:
When performing data analysis, refer to the data patterns and business rules stored in Memory.

Skills + Slash Commands

Slash Commands can reference Skills:
<!-- .codebuddy/commands/analyze-data.md -->
Use the data-analysis skill to analyze the file: $1

Skills + MCP

Skills can call external tools provided by MCP if they are in allowed-tools.

Next

Slash commands - Learn about user-initiated commands.
Settings - Configure tool permissions.
MCP integration - Extend external tool capabilities.


Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback