DeepSeek Harness Skills: Build Reusable AI Workflows

This tutorial covers the creation of custom Skill within DeepSeek Harness (dsh). A custom Skill is a reusable instruction set stored in a local directory. It uses YAML frontmatter for metadata definition and Markdown body content to define step-by-step workflows for AI agents. According to DeepSeek Harness official documentation, Skills are designed to be instruction sets decoupled from models and tools. The system supports discovery at project, user and custom directory levels. This allows engineering teams to encode team standards, code review checklists and release note templates into reusable agent workflows.

Understand the Difference Between Skill and Plugins

It is critical to distinguish Skills from plugins before implementation.

• Skill: Defines the sequence of steps required to complete a task. It does not require TypeScript development and does not register new tools. When loaded, it injects instruction context into the agent, guiding the agent to leverage existing files, shell commands, search or MCP tools.
• Plugin: Extends runtime capability by registering new executable tools for the agent.

The official repository splits Skill processing into three phases: discovery, directory indexing and loading. The scanner first parses the YAML frontmatter and indexes the Skill name and description for quick lookup. Full Markdown content is only loaded into context when the user explicitly invokes the Skill or a task matches its description. This design keeps routine task indexing lightweight; large instruction bodies are only pulled on demand.

Step 1: Select Skill Storage Location

The recommended path for project-shared Skills is <projectRoot>/.dsh/skills. If sharing with other agent tooling, you may use <projectRoot>/.agents/skills. Personal Skills can be placed at ~/.dsh/skills or ~/.agents/skills. Teams can define additional lookup directories via customSkillDirs.

Discovery priority is ranked numerically; lower rank values override higher ones when duplicate Skill names exist.

> Note: The scanner only reads files directly inside target directories. It does not recursively scan nested subfolders. Valid file patterns: <name>/SKILL.md or <name>.md.

Step 2: Build a Minimal Working Skill

This example creates a release-note Skill, which parses Git diff and generates human-readable release announcements. Execute these commands from your project root directory:

mkdir -p .dsh/skills/release-note
touch .dsh/skills/release-note/SKILL.md

Directory names must use kebab-case and match the name field inside frontmatter. Paste the content into SKILL.md:

---
name: release-note
description: Generate user-facing Chinese release notes from Git diff, including changes, impacts and upgrade guidance
whenToUse: Trigger when users request changelog summary, version description or release announcement drafting
---
# Release Note Workflow
1. Read Git diff between current branch and previous release version
2. Classify changes into new features, bug fixes, compatibility breaks and performance improvements

The frontmatter requires at minimum name and description. The optional whenToUse field defines matching triggers. Since the directory index only displays name and description, the description field must independently explain the problem the Skill solves.

Step3: Launch Harness and Discover Your Skill

Start the web UI using the official npm entrypoint:

npx @deepseek-ai/dsh web

Once inside the workspace, send a simple prompt to test discovery, for example list all available skills in current project. When formatted correctly, release-note will appear in the skill catalog. The file watcher monitors skill directories; newly added, modified or deleted Skills refresh the index on the next agent step. Editing only the Markdown body loads updated instructions without reindexing metadata.

Troubleshooting checklist if your Skill fails to appear:

1. Confirm working directory sits inside a Git repository root
2. Verify file path is exactly .dsh/skills/release-note/SKILL.md
3. Check the name field uses only lowercase letters, numbers and hyphens
4. Ensure frontmatter contains both name and description
5. Confirm no nested subdirectories (recursive scanning is disabled)

Two Invocation Modes: Automatic Matching and Explicit Call

The agent can invoke Skills in two separate modes.

1. Automatic matching: When user task semantics match the Skill’s description, the agent loads the Skill instruction automatically using the skill tool.
2. Explicit invocation: User manually triggers via slash command, e.g. /release-note. This is suitable for workflows that require strict execution every time.

Example explicit call:

/release-note
Generate release notes for v0.3.0 from current commit diff, focus on API compatibility breaking changes.

You can add optional frontmatter flags to control invocation behavior:
Disable automatic model loading while retaining manual slash command access:

disable-model-invocation: true

Hide the Skill from user slash commands, reserving it only for programmatic model usage:

user-invocable: false

These flags manage indexing rules, but they do not replace permission controls. File deletion, shell execution and public publishing actions still rely on DeepSeek Harness audit and sandbox policy.

Five Key Practices to Write Stable Skills

1. Define input and output schema first, then write steps. For instance: "Input: Git diff text, Output: Chinese summary within 300 words". Clear boundaries help the agent produce consistent outputs.
2. Enforce mandatory checks as numbered steps. Place recommendations at the end to avoid the agent treating suggestions as hard requirements.
3. Avoid embedding lengthy reference documents directly in SKILL.md. Full content stays in the agent context once loaded; oversized Skills consume excessive token budget. Move templates and reference materials to adjacent files, only reference relative paths in the main workflow.
4. Require human confirmation for destructive operations. Before running publish commands, display the target command and environment and wait for user approval. Skills are instruction templates, not security boundaries and cannot replace authorization checks.
5. Validate with real test cases. Prepare one successful example, one case with incomplete input and one rejected edge case, to prevent the agent from fabricating facts.

Common Troubleshooting

Skill not visible in directory index

The most frequent causes: nested folder structure, missing description in frontmatter, or name containing uppercase characters or underscores. The discovery scanner skips files with invalid formatting.

Modifications to SKILL.md do not take effect

Skill content is cached once loaded. Updates to the Markdown body only apply for subsequent tool invocations. Previously generated tool outputs remain unchanged after edits. Restart the workflow session to reload changes.

Can a Skill register brand-new tools?

No. Skills guide agents to call existing tools. To register new executable tools, you must develop DeepSeek Harness plugins via the plugin development flow. Skills cannot add new tool definitions.

Managing Multi-Model Agent Workflows and API Routing

DeepSeek Harness provides a powerful local skill orchestration layer, but teams running agent workloads across multiple LLM models often need centralized request management, rate limiting and usage auditing. Treerouter, an API gateway, can unify traffic routing across multiple model providers and log token consumption for agent sessions. This is especially helpful when your custom Skills make sequential chained API calls during multi-step task execution.

Teams building agent systems frequently separate local workflow definition (via Harness Skills) from remote API traffic governance. Skills define what the agent should do, while the API gateway controls how model requests are routed, throttled and monitored across production environments. This separation keeps Skill definitions lightweight and portable, without embedding routing logic inside every workflow file.

Final Takeaways

As of October 14, 2026, the Skill subsystem of DeepSeek Harness supports project, user and custom directory discovery, plus explicit /name invocation. The core insight for building reliable Skills is not to write extremely long instruction documents. Instead, clearly define inputs, outputs, step constraints and confirmation checkpoints so identical workflows remain stable under different prompts. Custom Skills turn repetitive engineering tasks into version-controlled, shareable agent modules, which greatly reduces redundant prompt writing for software teams.

Learn more: https://treerouter.com