// Use when writing, improving, or reviewing Dify user guide documentation. Covers pages in en/use-dify/, en/develop-plugin/, and en/self-host/. Triggers: "write docs for [feature]", "improve this page", "review this documentation section".
Use when editing, auditing, or creating OpenAPI specs for the Dify documentation repo. Applies to files in en/api-reference/. Covers formatting rules, error code conventions, example standards, operationId patterns.
Use when writing, rewriting, or auditing environment variable documentation for Dify self-hosted deployment. Applies to en/self-host/configuration/environments.mdx. Covers the full process from codebase tracing to user-facing descriptions.
Use when preparing documentation updates for a Dify release. User provides two version references to compare (e.g., v1.13.2 and v1.13.3, or v1.13.2 and main). Covers API reference, help documentation, environment variable changes, and UI i18n glossary impact.
Check formatting compliance in changed Chinese and Japanese documentation against writing-guides/formatting-guide.md, tools/translate/formatting-zh.md, and tools/translate/formatting-ja.md. Use after finalizing a translation batch, or when the user says "check formatting (zh/ja)", "check CJK formatting", or "format audit" on translated content.
Check formatting compliance in changed English documentation against writing-guides/formatting-guide.md. Use after finalizing a draft, or when the user says "check formatting", "format audit", "format check" on English content.
Research a Dify feature before writing or optimizing documentation. Use when starting any doc task that requires understanding a feature's implementation, user pain points, or community feedback. Triggers: 'research this feature', 'investigate the code for', 'what do users say about', 'let's understand how X works before writing', or any documentation task where the current docs are being rewritten or significantly expanded.
| name | dify-docs-guides |
| description | Use when writing, improving, or reviewing Dify user guide documentation. Covers pages in en/use-dify/, en/develop-plugin/, and en/self-host/. Triggers: "write docs for [feature]", "improve this page", "review this documentation section". |
Read these files before beginning any documentation task:
writing-guides/style-guide.md — voice, tone, writing patternswriting-guides/formatting-guide.md — MDX formatting, Mintlify componentswriting-guides/glossary.md — standardized terminologyWhen optimizing Chinese or Japanese translations, also read:
tools/translate/formatting-zh.md or tools/translate/formatting-ja.mdAdjust tone and assumed knowledge based on the document path:
Product users building AI applications on Dify. Mix of developers and non-technical users. Assume basic AI familiarity but not infrastructure or deep coding knowledge. Explain technical concepts when they appear. Prioritize task completion and outcomes.
DevOps engineers and system administrators deploying Dify. Assume strong infrastructure knowledge (Docker, databases, networking, environment variables). Be precise with technical details. Don't over-explain standard operations.
Developers building custom Dify plugins. Assume strong Python skills and familiarity with Dify's core concepts. Focus on API contracts, extension points, and code patterns. Code examples are essential.
This is a team effort. The user brings documentation expertise and user empathy; Claude brings AI domain knowledge and broader technical perspective. Actively leverage this dynamic rather than passively executing writing tasks.
Explain the "why" behind AI concepts. When an AI concept comes up, explain why it's designed this way and what problem it solves—not just what it does. For example, if asked why a tool role appears in conversation history, explain from the LLM API mechanism level.
Help judge design decisions. When the user questions a product design: assess whether it's common in the AI field, clarify if it's Dify-specific or industry standard, and offer perspective on how users might understand it.
Provide analogies and concrete scenarios. When concepts are abstract, use specific scenarios rather than technical jargon. Help the user understand "why users need this feature" from a practical standpoint.
Analyze wording from user cognition perspective. When the user is unsure about phrasing, consider: Can users understand this term? Is it accurate in the AI context? Is there a term closer to the user's mental model?
Proactively flag issues. If a design seems unusual, a concept may have been misunderstood, or a term is inaccurate in the AI domain—speak up directly rather than waiting to be asked.
git fetch origin && git checkout main && git pull origin main. If the user specifies a different branch, substitute accordingly.main branch of the Dify codebase. The user will provide the codebase path or it will be configured as an additional working directory.When a feature is gated by or configured through environment variables (feature toggles, endpoints, self-host-only switches, worker classes), coordinate with the reference doc instead of duplicating it.
During feature research, check whether the feature has related environment variables:
docker/.env.example, api/configs/, and the feature's PR for any ENABLE_*, *_URL, worker, or socket settings tied to the feature.If the feature has related variables, use the dify-docs-env-vars skill to update en/self-host/configuration/environments.mdx in the same session. The reference doc is the single source of truth for variable semantics.
en/self-host/configuration/environments.mdx): exhaustive. Every variable gets a description covering purpose, defaults, interactions, and failure modes. Maintained via the dify-docs-env-vars skill.User Guides serve both SaaS (Dify Cloud) and self-hosted readers. Place self-host-only configuration in a callout rather than a dedicated H2 section. The callout surfaces the information clearly for self-hosters while letting SaaS readers skip past it without breaking the flow of the guide.
Choose the callout type by what the variables do:
<Note> — when the variables are mandatory for the feature to work. Without them, self-hosters will not be able to use the feature at all. Example: ENABLE_COLLABORATION_MODE gates the entire collaboration feature.<Info> — when the variables only customize existing behavior (tuning a default, switching backends, adjusting an endpoint). The feature works without them; these are optional knobs.Pattern (substitute <Note> or <Info> per the rule above):
<Note>
On self-hosted deployments, [feature] is turned off by default. Enable it by setting:
- `VAR_NAME` = `value`
- ...
See [Environment Variables](/en/self-host/configuration/environments#var_name) for details.
</Note>
Do not promote self-host config to an H2 section. Giving deployment-specific content equal weight with product-facing content clutters the guide for SaaS readers, who are the majority of the audience.
No overrides. Follow writing-guides/style-guide.md as written.
After completing the document, run the post-writing checks listed in writing-guides/index.md#post-writing-verification.