返回 DeepSeek-TUI-2026
SKILL.md
1 <!--
2 This SKILL.md is ported from OpenAI's codex repo (MIT-licensed).
3 Source: https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/skill-creator/SKILL.md
4 -->
5 ---
6 name: skill-creator
7 description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends deepseek's capabilities with specialized knowledge, workflows, or tool integrations.
8 metadata:
9 short-description: Create or update a skill
10 ---
11
12 # Skill Creator
13
14 This skill provides guidance for creating effective skills.
15
16 ## About Skills
17
18 Skills are modular, self-contained folders that extend deepseek's capabilities by providing
19 specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
20 domains or tasks—they transform deepseek from a general-purpose agent into a specialized agent
21 equipped with procedural knowledge that no model can fully possess.
22
23 ### What Skills Provide
24
25 1. Specialized workflows - Multi-step procedures for specific domains
26 2. Tool integrations - Instructions for working with specific file formats or APIs
27 3. Domain expertise - Company-specific knowledge, schemas, business logic
28 4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
29
30 ## Core Principles
31
32 ### Concise is Key
33
34 The context window is a public good. Skills share the context window with everything else deepseek needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
35
36 **Default assumption: deepseek is already very smart.** Only add context deepseek doesn't already have. Challenge each piece of information: "Does deepseek really need this explanation?" and "Does this paragraph justify its token cost?"
37
38 Prefer concise examples over verbose explanations.
39
40 ### Set Appropriate Degrees of Freedom
41
42 Match the level of specificity to the task's fragility and variability:
43
44 **High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
45
46 **Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
47
48 **Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
49
50 Think of deepseek as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
51
52 ### Protect Validation Integrity
53
54 You may use subagents during iteration to validate whether a skill works on realistic tasks or whether a suspected problem is real. This is most useful when you want an independent pass on the skill's behavior, outputs, or failure modes after a revision. Only do this when it is possible to start new subagents.
55
56 When using subagents for validation, treat that as an evaluation surface. The goal is to learn whether the skill generalizes, not whether another agent can reconstruct the answer from leaked context.
57
58 Prefer raw artifacts such as example prompts, outputs, diffs, logs, or traces. Give the minimum task-local context needed to perform the validation. Avoid passing the intended answer, suspected bug, intended fix, or your prior conclusions unless the validation explicitly requires them.
59
60 ### Anatomy of a Skill
61
62 Every skill consists of a required SKILL.md file and optional bundled resources:
63
64 ```
65 skill-name/
66 ├── SKILL.md (required)
67 │ ├── YAML frontmatter metadata (required)
68 │ │ ├── name: (required)
69 │ │ └── description: (required)
70 │ └── Markdown instructions (required)
71 ├── agents/ (recommended)
72 │ └── openai.yaml - UI metadata for skill lists and chips
73 └── Bundled Resources (optional)
74 ├── scripts/ - Executable code (Python/Bash/etc.)
75 ├── references/ - Documentation intended to be loaded into context as needed
76 └── assets/ - Files used in output (templates, icons, fonts, etc.)
77 ```
78
79 #### SKILL.md (required)
80
81 Every SKILL.md consists of:
82
83 - **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that deepseek reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.
84 - **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
85
86 #### Agents metadata (recommended)
87
88 - UI-facing metadata for skill lists and chips
89 - Read references/openai_yaml.md before generating values and follow its descriptions and constraints
90 - Create: human-facing `display_name`, `short_description`, and `default_prompt` by reading the skill
91 - Generate deterministically by passing the values as `--interface key=value` to `scripts/generate_openai_yaml.py` or `scripts/init_skill.py`
92 - On updates: validate `agents/openai.yaml` still matches SKILL.md; regenerate if stale
93 - Only include other optional interface fields (icons, brand color) if explicitly provided
94 - See references/openai_yaml.md for field definitions and examples
95
96 #### Bundled Resources (optional)
97
98 ##### Scripts (`scripts/`)
99
100 Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
101
102 - **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
103 - **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
104 - **Benefits**: Token efficient, deterministic, may be executed without loading into context
105 - **Note**: Scripts may still need to be read by deepseek for patching or environment-specific adjustments
106
107 ##### References (`references/`)
108
109 Documentation and reference material intended to be loaded as needed into context to inform deepseek's process and thinking.
110
111 - **When to include**: For documentation that deepseek should reference while working
112 - **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
113 - **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
114 - **Benefits**: Keeps SKILL.md lean, loaded only when deepseek determines it's needed
115 - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
116 - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
117
118 ##### Assets (`assets/`)
119
120 Files not intended to be loaded into context, but rather used within the output deepseek produces.
121
122 - **When to include**: When the skill needs files that will be used in the final output
123 - **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
124 - **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
125 - **Benefits**: Separates output resources from documentation, enables deepseek to use files without loading them into context
126
127 #### What to Not Include in a Skill
128
129 A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
130
131 - README.md
132 - INSTALLATION_GUIDE.md
133 - QUICK_REFERENCE.md
134 - CHANGELOG.md
135 - etc.
136
137 The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
138
139 ### Progressive Disclosure Design Principle
140
141 Skills use a three-level loading system to manage context efficiently:
142
143 1. **Metadata (name + description)** - Always in context (~100 words)
144 2. **SKILL.md body** - When skill triggers (<5k words)
145 3. **Bundled resources** - As needed by deepseek (Unlimited because scripts can be executed without reading into context window)
146
147 #### Progressive Disclosure Patterns
148
149 Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
150
151 **Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
152
153 **Pattern 1: High-level guide with references**
154
155 ```markdown
156 # PDF Processing
157
158 ## Quick start
159
160 Extract text with pdfplumber:
161 [code example]
162
163 ## Advanced features
164
165 - **Form filling**: See [FORMS.md](FORMS.md) for complete guide
166 - **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
167 - **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
168 ```
169
170 deepseek loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
171
172 **Pattern 2: Domain-specific organization**
173
174 For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
175
176 ```
177 bigquery-skill/
178 ├── SKILL.md (overview and navigation)
179 └── reference/
180 ├── finance.md (revenue, billing metrics)
181 ├── sales.md (opportunities, pipeline)
182 ├── product.md (API usage, features)
183 └── marketing.md (campaigns, attribution)
184 ```
185
186 When a user asks about sales metrics, deepseek only reads sales.md.
187
188 Similarly, for skills supporting multiple frameworks or variants, organize by variant:
189
190 ```
191 cloud-deploy/
192 ├── SKILL.md (workflow + provider selection)
193 └── references/
194 ├── aws.md (AWS deployment patterns)
195 ├── gcp.md (GCP deployment patterns)
196 └── azure.md (Azure deployment patterns)
197 ```
198
199 When the user chooses AWS, deepseek only reads aws.md.
200
201 **Pattern 3: Conditional details**
202
203 Show basic content, link to advanced content:
204
205 ```markdown
206 # DOCX Processing
207
208 ## Creating documents
209
210 Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
211
212 ## Editing documents
213
214 For simple edits, modify the XML directly.
215
216 **For tracked changes**: See [REDLINING.md](REDLINING.md)
217 **For OOXML details**: See [OOXML.md](OOXML.md)
218 ```
219
220 deepseek reads REDLINING.md or OOXML.md only when the user needs those features.
221
222 **Important guidelines:**
223
224 - **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
225 - **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so deepseek can see the full scope when previewing.
226
227 ## Skill Creation Process
228
229 Skill creation involves these steps:
230
231 1. Understand the skill with concrete examples
232 2. Plan reusable skill contents (scripts, references, assets)
233 3. Initialize the skill (run init_skill.py)
234 4. Edit the skill (implement resources and write SKILL.md)
235 5. Validate the skill (run quick_validate.py)
236 6. Iterate based on real usage and forward-test complex skills.
237
238 Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
239
240 ### Skill Naming
241
242 - Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> `plan-mode`).
243 - When generating names, generate a name under 64 characters (letters, digits, hyphens).
244 - Prefer short, verb-led phrases that describe the action.
245 - Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).
246 - Name the skill folder exactly after the skill name.
247
248 ### Step 1: Understanding the Skill with Concrete Examples
249
250 Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
251
252 To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
253
254 For example, when building an image-editor skill, relevant questions include:
255
256 - "What functionality should the image-editor skill support? Editing, rotating, anything else?"
257 - "Can you give some examples of how this skill would be used?"
258 - "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
259 - "What would a user say that should trigger this skill?"
260 - "Where should I create this skill? If you do not have a preference, I will place it in `$DEEPSEEK_HOME/skills` (or `~/.deepseek/skills` when `DEEPSEEK_HOME` is unset) so deepseek can discover it automatically."
261
262 To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
263
264 Conclude this step when there is a clear sense of the functionality the skill should support.
265
266 ### Step 2: Planning the Reusable Skill Contents
267
268 To turn concrete examples into an effective skill, analyze each example by:
269
270 1. Considering how to execute on the example from scratch
271 2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
272
273 Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
274
275 1. Rotating a PDF requires re-writing the same code each time
276 2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
277
278 Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
279
280 1. Writing a frontend webapp requires the same boilerplate HTML/React each time
281 2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
282
283 Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
284
285 1. Querying BigQuery requires re-discovering the table schemas and relationships each time
286 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
287
288 To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
289
290 ### Step 3: Initializing the Skill
291
292 At this point, it is time to actually create the skill.
293
294 Skip this step only if the skill being developed already exists. In this case, continue to the next step.
295
296 Before running `init_skill.py`, ask where the user wants the skill created. If they do not specify a location, default to `$DEEPSEEK_HOME/skills`; when `DEEPSEEK_HOME` is unset, fall back to `~/.deepseek/skills` so the skill is auto-discovered.
297
298 When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
299
300 Usage:
301
302 ```bash
303 scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
304 ```
305
306 Examples:
307
308 ```bash
309 scripts/init_skill.py my-skill --path "${DEEPSEEK_HOME:-$HOME/.deepseek}/skills"
310 scripts/init_skill.py my-skill --path "${DEEPSEEK_HOME:-$HOME/.deepseek}/skills" --resources scripts,references
311 scripts/init_skill.py my-skill --path ~/work/skills --resources scripts --examples
312 ```
313
314 The script:
315
316 - Creates the skill directory at the specified path
317 - Generates a SKILL.md template with proper frontmatter and TODO placeholders
318 - Creates `agents/openai.yaml` using agent-generated `display_name`, `short_description`, and `default_prompt` passed via `--interface key=value`
319 - Optionally creates resource directories based on `--resources`
320 - Optionally adds example files when `--examples` is set
321
322 After initialization, customize the SKILL.md and add resources as needed. If you used `--examples`, replace or delete placeholder files.
323
324 Generate `display_name`, `short_description`, and `default_prompt` by reading the skill, then pass them as `--interface key=value` to `init_skill.py` or regenerate with:
325
326 ```bash
327 scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value
328 ```
329
330 Only include other optional interface fields when the user explicitly provides them. For full field descriptions and examples, see references/openai_yaml.md.
331
332 ### Step 4: Edit the Skill
333
334 When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of deepseek to use. Include information that would be beneficial and non-obvious to deepseek. Consider what procedural knowledge, domain-specific details, or reusable assets would help another deepseek instance execute these tasks more effectively.
335
336 After substantial revisions, or if the skill is particularly tricky, you should use subagents to forward-test the skill on realistic tasks or artifacts. When doing so, pass the artifact under validation rather than your diagnosis of what is wrong, and keep the prompt generic enough that success depends on transferable reasoning rather than hidden ground truth.
337
338 #### Start with Reusable Skill Contents
339
340 To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
341
342 Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
343
344 If you used `--examples`, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.
345
346 #### Update SKILL.md
347
348 **Writing Guidelines:** Always use imperative/infinitive form.
349
350 ##### Frontmatter
351
352 Write the YAML frontmatter with `name` and `description`:
353
354 - `name`: The skill name
355 - `description`: This is the primary triggering mechanism for your skill, and helps deepseek understand when to use the skill.
356 - Include both what the Skill does and specific triggers/contexts for when to use it.
357 - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to deepseek.
358 - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when deepseek needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
359
360 Do not include any other fields in YAML frontmatter.
361
362 ##### Body
363
364 Write instructions for using the skill and its bundled resources.
365
366 ### Step 5: Validate the Skill
367
368 Once development of the skill is complete, validate the skill folder to catch basic issues early:
369
370 ```bash
371 scripts/quick_validate.py <path/to/skill-folder>
372 ```
373
374 The validation script checks YAML frontmatter format, required fields, and naming rules. If validation fails, fix the reported issues and run the command again.
375
376 ### Step 6: Iterate
377
378 After testing the skill, you may detect the skill is complex enough that it requires forward-testing; or users may request improvements.
379
380 User testing often this happens right after using the skill, with fresh context of how the skill performed.
381
382 **Forward-testing and iteration workflow:**
383
384 1. Use the skill on real tasks
385 2. Notice struggles or inefficiencies
386 3. Identify how SKILL.md or bundled resources should be updated
387 4. Implement changes and test again
388 5. Forward-test if it is reasonable and appropriate
389
390 ## Forward-testing
391
392 To forward-test, launch subagents as a way to stress test the skill with minimal context.
393 Subagents should *not* know that they are being asked to test the skill. They should be treated as
394 an agent asked to perform a task by the user. Prompts to subagents should look like:
395 `Use $skill-x at /path/to/skill-x to solve problem y`
396 Not:
397 `Review the skill at /path/to/skill-x; pretend a user asks you to...`
398
399 Decision rule for forward-testing:
400 - Err on the side of forward-testing
401 - Ask for approval if you think there's a risk that forward-testing would:
402 * take a long time,
403 * require additional approvals from the user, or
404 * modify live production systems
405
406 In these cases, show the user your proposed prompt and request (1) a yes/no decision, and
407 (2) any suggested modifictions.
408
409 Considerations when forward-testing:
410 - use fresh threads for independent passes
411 - pass the skill, and a request in a similar way the user would.
412 - pass raw artifacts, not your conclusions
413 - avoid showing expected answers or intended fixes
414 - rebuild context from source artifacts after each iteration
415 - review the subagent's output and reasoning and emitted artifacts
416 - avoid leaving artifacts the agent can find on disk between iterations;
417 clean up subagents' artifacts to avoid additional contamination.
418
419 If forward-testing only succeeds when subagents see leaked context, tighten the skill or the
420 forward-testing setup before trusting the result.
421
421 lines MARKDOWN