How to Configure Agent Skills in Deep Code CLI: A Complete Guide

Agent Skills in Deep Code CLI are configured by placing markdown files named SKILL.md in either ~/.agents/skills/<skill-name>/ for user-level access or ./.deepcode/skills/<skill-name>/ for project-specific capabilities.

Deep Code CLI, part of the deepseek-ai/awesome-deepseek-agent ecosystem, extends its interactive coding assistant through customizable Agent Skills. These skills allow you to inject domain-specific expertise into the DeepSeek model using simple markdown configuration files.

Understanding Agent Skill Discovery Paths

The Deep Code CLI discovers skills at two hard-coded locations defined in docs/deepcode.md (lines 75-81):

• User-level scope: ~/.agents/skills/<skill-name>/SKILL.md
• Project-level scope: ./.deepcode/skills/<skill-name>/SKILL.md

When you launch the CLI, it recursively scans both directories to build the skill registry. User-level skills persist across all projects, while project-level skills are scoped to the current working directory and can be version-controlled alongside your source code.

Architecture of the Skill System

The skill execution pipeline follows four distinct phases:

1. Discovery – On startup, the CLI walks both ~/.agents/skills and ./.deepcode/skills directories.
2. Parsing – Each SKILL.md file is parsed for metadata blocks including title, description, and parameter tables.
3. Registration – Parsed skills are indexed in an internal registry keyed by the directory name (<skill-name>).
4. Execution – When invoked, the CLI sends the skill's markdown content as a system prompt to the DeepSeek model, optionally injecting user-provided arguments.

Creating Your First Agent Skill

Step 1: Create the Skill Directory

Create a directory for your skill using either the global or local path:

# User-level skill (available everywhere)

mkdir -p ~/.agents/skills/my-skill

# Project-level skill (versioned with repository)

mkdir -p ./.deepcode/skills/my-skill

Step 2: Write the SKILL.md Metadata

Create a SKILL.md file inside the directory with a standardized structure:

# Skill Title

A concise description of what the skill does and when to use it.

## Parameters

| Name | Type | Description |
|------|------|-------------|
| `param1` | string | Description of the first parameter. |
| `param2` | boolean | Description of the second parameter. |

## Example

/my-skill param1="value" param2=true

The metadata block must include the title and description. The Parameters table defines the schema for arguments passed via the command line.

Step 3: Reload and Invoke

Restart the Deep Code CLI or press Ctrl+R to force a rescan of skill directories. Access your skill using either method:

• Press / to open the interactive skill picker
• Type /skill-name directly in the prompt followed by arguments

Agent Skill Configuration Examples

User-Level Skill: Code Writer

Place this file at ~/.agents/skills/code-writer/SKILL.md:

# Code Writer

Generate a code snippet based on a natural language description.

## Parameters

| Name | Type | Description |
|------|------|-------------|
| `description` | string | Natural-language description of desired code. |
| `language` | string | Target programming language (python, js, rust, etc.). |

## Example

/code-writer description="read a file line-by-line" language=python

Invoke it in the CLI:

$ deepcode
> /code-writer description="fetch JSON from a URL" language=js

Project-Level Skill: Regex Tester

Create a version-controlled skill inside your repository:

mkdir -p ./.deepcode/skills/regex-tester
cat > ./.deepcode/skills/regex-tester/SKILL.md <<'EOF'

# Regex Tester

Test a regular expression against sample text and explain the matches.

## Parameters

| Name | Type | Description |
|------|------|-------------|
| `pattern` | string | The regular expression pattern to test. |
| `text` | string | Sample text to evaluate against the pattern. |

## Example

/regex-tester pattern="\d+" text="abc123def"
EOF

Commit the ./.deepcode/skills directory to share the capability with teammates.

Security Considerations and Settings

Agent Skills are read-only markdown files and cannot execute arbitrary shell commands directly. However, certain capabilities require explicit enablement in your configuration.

According to docs/deepcode.md (lines 44-53), actions like web notifications or external searches must be explicitly enabled in ~/.deepcode/settings.json:

{
  "notificationsEnabled": true,
  "webSearchEnabled": false
}

Because skills are parsed as markdown and sent as system prompts to the model, they inherit the security boundaries of the DeepSeek API rather than executing local code.

Summary

• Agent Skills in Deep Code CLI use a markdown-based configuration system stored in SKILL.md files.
• Skills install to either ~/.agents/skills/<name>/ (global) or ./.deepcode/skills/<name>/ (project-local).
• Each skill requires a metadata block with title, description, and optional parameter tables.
• The CLI parses these files on startup and sends them as system prompts when invoked via /skill-name.
• Project-level skills can be version-controlled, while user-level skills provide cross-project reusability.

Frequently Asked Questions

What file format is used for Agent Skills?

Agent Skills use standard markdown files named exactly SKILL.md. The CLI parses these files for structured metadata including the title, description, and parameter tables, but the underlying format is plain markdown that you can edit with any text editor.

Can I share Agent Skills with my team?

Yes. Place your skills in the ./.deepcode/skills/<skill-name>/ directory relative to your project root. Since these files reside within your repository, they can be committed to version control and shared with teammates. When colleagues clone the repository and run Deep Code CLI, the skills will automatically appear in their skill picker.

How does the CLI execute a skill?

When you invoke a skill by typing /skill-name, the CLI reads the associated SKILL.md content and transmits it to the DeepSeek model as a system prompt. The model interprets the skill's instructions and any provided arguments, then generates the appropriate response. No local code execution occurs; the skill's logic runs entirely within the model's context window.

Are there security risks with custom skills?

Skills are inherently safe because they are read-only markdown files that cannot execute shell commands or access the filesystem directly. However, if a skill instructs the model to suggest code that performs dangerous operations, always review generated content before execution. Sensitive actions like web notifications require explicit opt-in via ~/.deepcode/settings.json.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}