agent-development
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for DeepSeek Harness plugins.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 21
- Forks
- 2
01 前言 Front Matter
- name
- agent-development
- description
- This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for DeepSeek Harness plugins.
02 资源文件 6
- 参考文档examples/agent-creation-prompt.md9.6 KB
- 参考文档examples/complete-agent-examples.md13.2 KB
- 参考文档references/agent-creation-system-prompt.md9.5 KB
- 参考文档references/system-prompt-design.md9.8 KB
- 参考文档references/triggering-examples.md8.7 KB
- 脚本scripts/validate-agent.sh5.2 KB
03 SKILL.md 正文
Agent Development for DeepSeek Harness Plugins
Overview
Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.
Key concepts:
- Agents are FOR autonomous work, commands are FOR user-initiated actions
- Markdown file format with YAML frontmatter
- Triggering via description field with examples
- System prompt defines agent behavior
- Optional model routing and tool restriction
Agent File Structure
Complete Format
---
name: agent-identifier
description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
model: inherit
tools: ["Read", "Write", "Grep"]
---
You are [agent role description]...
## When to invoke
[Two to four representative scenarios written as prose, e.g.:]
- **[Scenario name].** [What the situation looks like and what the agent should do.]
- **[Scenario name].** [Same.]
**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]
**Analysis Process:**
[Step-by-step workflow]
**Output Format:**
[What to return]
Frontmatter Fields
name (required)
Agent identifier used for namespacing and invocation.
Format: lowercase, numbers, hyphens only Length: 3-50 characters Pattern: Must start and end with alphanumeric
Good examples:
code-reviewertest-generatorapi-docs-writersecurity-analyzer
Bad examples:
helper(too generic)-agent-(starts/ends with hyphen)my_agent(underscores not allowed)ag(too short, < 3 chars)
description (required)
Defines when the agent should trigger this agent. This is the most critical field — it is loaded into context whenever the agent is registered, so the harness can decide when to dispatch.
Must include:
- Triggering conditions ("Use this agent when...")
- A short prose summary of the typical trigger scenarios
- A pointer to a "When to invoke" section in the agent body for the detailed worked scenarios
Format:
Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
Best practices:
- Name 2-4 trigger scenarios in the prose summary
- Cover both proactive (assistant invokes itself) and reactive (user requests) triggering
- Cover different phrasings of the same intent
- Be specific about when NOT to use the agent
- Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptions
model (optional)
Which model the agent should use.
Options:
inherit- Use same model as parent (recommended)- exact
provider+modelpair - Route the child to a specific model
Recommendation: Omit the field, or use inherit, unless the agent needs specific model capabilities.
tools (optional)
Restrict agent to specific tools.
Format: Array of tool names
tools: ["Read", "Write", "Grep", "Bash"]
Default: If omitted, agent has access to all tools
Best practice: Limit tools to minimum needed (principle of least privilege)
Common tool sets:
- Read-only analysis:
["Read", "Grep", "Glob"] - Code generation:
["Read", "Write", "Grep"] - Testing:
["Read", "Bash", "Grep"] - Full access: Omit field or use
["*"]
System Prompt Design
The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
Structure
Standard template:
You are [role] specializing in [domain].
**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]
**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]
**Quality Standards:**
- [Standard 1]
- [Standard 2]
**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]
**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]
Best Practices
✅ DO:
- Write in second person ("You are...", "You will...")
- Be specific about responsibilities
- Provide step-by-step process
- Define output format
- Include quality standards
- Address edge cases
- Keep under 10,000 characters
❌ DON'T:
- Write in first person ("I am...", "I will...")
- Be vague or generic
- Omit process steps
- Leave output format undefined
- Skip quality guidance
- Ignore error cases
Creating Agents
Method 1: AI-Assisted Generation
Use this prompt pattern (extracted from DeepSeek Harness):
Create an agent configuration based on this request: "[YOUR DESCRIPTION]"
Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
- Clear behavioral boundaries
- Specific methodologies
- Edge case handling
- Output format
- A "When to invoke" section listing 2-4 trigger scenarios as prose bullets
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions and a short prose summary of trigger scenarios
Return JSON with:
{
"identifier": "agent-name",
"whenToUse": "Use this agent when... Typical triggers include [...]. See \"When to invoke\" in the agent body.",
"systemPrompt": "You are..."
}
Then convert to agent file format with frontmatter.
See examples/agent-creation-prompt.md for complete template.
Method 2: Manual Creation
- Choose agent identifier (3-50 chars, lowercase, hyphens)
- Write description with examples
- Leave model unset (inherits the parent route)
- Define tools (if restricting access)
- Write system prompt with structure above
- Save as
com.deepseek.harness/agents/agent-name.md
Validation Rules
Identifier Validation
✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)
Rules:
- 3-50 characters
- Lowercase letters, numbers, hyphens only
- Must start and end with alphanumeric
- No underscores, spaces, or special characters
Description Validation
Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples
System Prompt Validation
Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format
Agent Organization
Plugin Agents Directory
plugin-name/
└── agents/
├── analyzer.md
├── reviewer.md
└── generator.md
All .md files in com.deepseek.harness/agents/ are auto-discovered.
Namespacing
Agents are namespaced automatically:
- Single plugin:
agent-name - With subdirectories:
plugin:subdir:agent-name
Testing Agents
Test Triggering
Create test scenarios to verify agent triggers correctly:
- Write agent with specific triggering examples
- Use similar phrasing to examples in test
- Check the agent loads the agent
- Verify agent provides expected functionality
Test System Prompt
Ensure system prompt is complete:
- Give agent typical task
- Check it follows process steps
- Verify output format is correct
- Test edge cases mentioned in prompt
- Confirm quality standards are met
Quick Reference
Minimal Agent
---
name: simple-agent
description: Use this agent when [condition]. Typical triggers include [trigger 1] and [trigger 2]. See "When to invoke" in the agent body.
model: inherit
---
You are an agent that [does X].
## When to invoke
- **[Scenario A].** [Description.]
- **[Scenario B].** [Description.]
Process:
1. [Step 1]
2. [Step 2]
Output: [What to provide]
Frontmatter Fields Summary
| Field | Required | Format | Example |
|---|---|---|---|
| name | Yes | lowercase-hyphens | code-reviewer |
| description | Yes | Prose triggers | Use when... Typical triggers include... |
| model | No | inherit, or exact provider + model pair |
inherit |
| tools | No | Array of tool names | ["Read", "Grep"] |
Best Practices
DO:
- ✅ Name 2-4 trigger scenarios in the description (as prose)
- ✅ Put detailed worked scenarios in a "When to invoke" body section, as prose bullets
- ✅ Write specific triggering conditions
- ✅ Use
inheritfor model unless specific need - ✅ Choose appropriate tools (least privilege)
- ✅ Write clear, structured system prompts
- ✅ Test agent triggering thoroughly
DON'T:
- ❌ Use generic descriptions without trigger scenarios
- ❌ Omit triggering conditions
- ❌ Pin a model without a reason
- ❌ Grant unnecessary tool access
- ❌ Write vague system prompts
- ❌ Skip testing
Additional Resources
Reference Files
For detailed guidance, consult:
references/system-prompt-design.md- Complete system prompt patternsreferences/triggering-examples.md- Example formats and best practicesreferences/agent-creation-system-prompt.md- The exact prompt from DeepSeek Harness
Example Files
Working examples in examples/:
agent-creation-prompt.md- AI-assisted agent generation templatecomplete-agent-examples.md- Full agent examples for different use cases
Utility Scripts
Development tools in scripts/:
validate-agent.sh- Validate agent file structuretest-agent-trigger.sh- Test if agent triggers correctly
Implementation Workflow
To create an agent for a plugin:
- Define agent purpose and triggering conditions
- Choose creation method (AI-assisted or manual)
- Create
com.deepseek.harness/agents/agent-name.mdfile - Write frontmatter with all required fields
- Write system prompt following best practices
- Name 2-4 trigger scenarios in description (prose) and detail them in a "When to invoke" body section
- Validate with
scripts/validate-agent.sh - Test triggering with real scenarios
- Document agent in plugin README
Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.
04 同仓库更多 Skills
verify
Verify that a code change actually does what it's supposed to by running the app and observing behavior. Use when asked to verify a PR, confirm a fix works, test a change manually, check that a feature works, or validate local changes before pushing.
simplify
Review changed code for reuse, quality, and efficiency, then fix any issues found. Use when the user asks to "simplify the code", "clean up the diff", "reduce duplication in my changes", or after finishing a feature before committing.
insight
Analyze this machine's DeepSeek Harness session history and report how sessions actually go — operating style, what works, friction points, and what to try next. Use when the user asks "how have I been using this", "analyze my sessions", "make an insight report", or wants a retrospective.
init
Set up a minimal AGENTS.md (and optionally skills and hooks) for this repo. Use when the user asks to "initialize the project", "generate AGENTS.md", "set up project instructions", or runs /init.
explore
Fast read-only codebase exploration that returns a report instead of filling the main context. Use when the user asks to "explore the codebase", "find where X is handled", "how does Y work", or when a search would take many reads to answer.
automation-recommender
Analyze a codebase and recommend DeepSeek Harness automations (hooks, subagents, skills, plugins, MCP servers). Use when user asks for automation recommendations, wants to optimize their DeepSeek Harness setup, mentions improving DeepSeek Harness workflows, asks how to first set up DeepSeek Harness for a project, or wants to know what DeepSeek Harness features they should use.