Dify Tool Plugin Developer

Guide AI agents through complete Dify tool plugin development using official documentation and direct CLI commands.

When to Use This Skill

Activate this skill when user:

•Mentions "Dify plugin", "Dify tool", or "Dify development"
•Wants to create custom Dify functionality
•Needs to extend Dify with custom tools
•Asks about developing for Dify
•Wants to build API integrations for Dify

Agent Responsibilities

⚠️ IMPORTANT: You (the AI agent) are responsible for:

•✅ Creating and editing all files yourself (YAML, Python, etc.)
•✅ Running all CLI commands directly
•✅ Implementing the code based on loaded documentation
•✅ Testing the plugin with remote debugging
•✅ Packaging the final .difypkg

DO NOT:

•❌ Just tell the user how to do these tasks
•❌ Provide instructions without executing
•❌ Guide the user to run commands themselves

YOU execute everything. The user provides requirements and confirms results.

Critical Rule: MANDATORY Documentation Loading

⚠️ BEFORE writing ANY code, you MUST load the referenced official documentation

The Dify plugin framework has STRICT requirements:

•Exact Python class structures with specific method signatures
•Precise YAML formatting and required fields
•Strict import patterns that must be followed exactly
•Specific parameter handling conventions

DO NOT guess, assume, or improvise. ALWAYS fetch and read the official documentation first.

Documentation Fetching

To fetch official Dify documentation, use curl:

bash

curl -s https://docs.dify.ai/plugin-dev-en/[doc-filename].md

Available Documentation (see references/doc-map.md for complete details on what each contains):

•0221-initialize-development-tools.md - CLI installation and setup
•0222-tool-plugin.md - Complete tool plugin development guide
•0222-debugging-logs.md - Logging and debugging techniques
•0222-tool-oauth.md - OAuth authentication implementation

MANDATORY Loading Points:

•Before Phase 2 (initialization): Load 0222-tool-plugin.md
•Before Phase 3 (implementation): Re-load 0222-tool-plugin.md (Developing section)
•If OAuth needed: Load 0222-tool-oauth.md
•During debugging: Load 0222-debugging-logs.md

Development Workflow

Follow this 5-phase workflow in sequence. Do not skip phases or documentation loading.

PHASE 1: Setup & Planning

FIRST: Load references/doc-map.md to understand the documentation structure

Gather Requirements - Ask the user:

•"What functionality should this tool provide?"
•"Does it need to call external APIs? If so, which APIs?"
•"Does it require OAuth authentication? (e.g., GitHub, Google, Slack)"
•"What inputs should users provide to this tool?"
•"What outputs should the tool return?"

Determine Requirements:

•Tool name (lowercase, hyphens only)
•Tool functionality description
•Required permissions (network access, storage, etc.)
•OAuth requirement (yes/no)
•Python package dependencies (requests, etc.)
•External API endpoints

Verify Dify CLI Installation:

bash

dify version

If the CLI is not installed or returns an error:

•LOAD: https://docs.dify.ai/plugin-dev-en/0221-initialize-development-tools.md
•Follow the installation instructions for the user's operating system
•Verify installation with dify version

Option 2: Use Helper Script (Recommended)

For automated installation, use the provided helper script:

bash

python scripts/install_cli.py

This script will:

•Detect your operating system and architecture automatically
•Download the latest Dify CLI version from GitHub
•Make the binary executable
•Verify the installation

Optional flags:

bash

# Install specific version
python scripts/install_cli.py --version 0.4.0

# Install to custom directory
python scripts/install_cli.py --path ~/bin

# Both
python scripts/install_cli.py --version 0.4.0 --path /usr/local/bin

The script provides:

•✅ Automatic platform detection (macOS/Linux/Windows, AMD64/ARM64)
•✅ Latest version detection from GitHub API
•✅ Progress indicator during download
•✅ Automatic executable permissions
•✅ Installation verification
•✅ PATH setup instructions

PHASE 1.5: Load Required Documentation (MANDATORY)

⚠️ BEFORE writing ANY code, load the specific documentation needed for the planned requirements.

Based on the requirements gathered in Phase 1, determine which documentation to load:

Required Documentation (ALWAYS LOAD)

1. Tool Plugin Guide (MANDATORY for all plugins):

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-tool-plugin.md

Read sections:

•File structure requirements
•YAML configuration syntax
•Tool class implementation patterns
•Parameter handling
•Message types

2. Debugging Guide (MANDATORY for testing):

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-debugging-logs.md

Conditional Documentation (Load if needed)

3. OAuth Guide (IF OAuth authentication required):

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-tool-oauth.md

Load this if the requirements include:

•GitHub integration
•Google services integration
•Slack integration
•Any OAuth-based authentication

4. Initialize Tools (IF CLI not installed):

bash

curl -s https://docs.dify.ai/plugin-dev-en/0221-initialize-development-tools.md

How to Determine What to Load

Based on Phase 1 requirements:

Requirement	Documentation to Load
Basic tool functionality	tool-plugin.md (always)
API integration	tool-plugin.md + debugging-logs.md
OAuth authentication	tool-plugin.md + tool-oauth.md + debugging-logs.md
Complex logic	tool-plugin.md + debugging-logs.md + examples.md
CLI installation needed	initialize-development-tools.md

⚠️ DO NOT skip this phase. Loading the wrong documentation or insufficient documentation will result in incorrect code with syntax errors.

After loading, confirm:

• Understand the exact YAML structure required
• Know the Tool class pattern to follow
• Clear on parameter handling methods
• Understand message types available
• Know OAuth implementation steps (if applicable)

Only proceed to Phase 2 after loading and understanding the required documentation.

PHASE 2: Initialize Project

⚠️ MANDATORY: Load the tool-plugin.md documentation BEFORE proceeding

Fetch Documentation:

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-tool-plugin.md

Read These Sections:

•"Prerequisites"
•"Creating a New Project"
•"Choosing Plugin Type and Template"

Initialize the Plugin:

Use the dify plugin init command with appropriate flags:

bash

dify plugin init \
  --name "your-tool-name" \
  --author "author-name" \
  --description "Clear, concise tool description" \
  --category tool \
  --language python \
  --min-dify-version "1.9.0" \
  --allow-network \      # Include if API access needed
  --allow-storage \      # Include if storage needed
  --quick                 # Skip interactive prompts

Available Permission Flags:

•--allow-network - For external API calls
•--allow-storage - For persistent data storage
•--allow-tool - To invoke other Dify tools
•--allow-llm - To invoke language models
•--storage-size <bytes> - Specify storage limit

Verify Project Structure:

bash

ls -la your-tool-name/

Expected files and directories:

•manifest.yaml - Plugin manifest configuration
•provider/ - Provider definitions and credential validation
•tools/ - Tool implementations (YAML + Python files)
•main.py - Plugin entry point
•requirements.txt - Python dependencies
•.env.example - Environment variables template

If any files are missing, re-run the init command or check for errors.

PHASE 3: Implement Tool

⚠️ MANDATORY: Re-read the tool-plugin.md "Developing the Tool Plugin" section

This section contains CRITICAL information:

•Exact file structure requirements
•YAML syntax for tools/*.yaml
•Tool class structure for tools/*.py
•Parameter handling patterns
•Message type formats and usage
•Import statement patterns

Fetch Documentation Again:

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-tool-plugin.md
# Focus on section "Developing the Tool Plugin"

If OAuth is Required:

⚠️ MANDATORY: Load the complete OAuth documentation

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-tool-oauth.md

Read all sections:

•Background (OAuth flows explained)
•Define OAuth Schema in Provider Manifest
•Complete Required OAuth Methods in Tool Provider
•Access Tokens in Your Tools
•Specify the Correct Versions

Implementation Steps:

1. Edit `tools/*.yaml`

Follow the exact YAML structure from the documentation:

yaml

identity:
  name: tool-name                    # Must match filename
  author: author-name
  label:
    en_US: Tool Display Name
    zh_Hans: 工具显示名称           # Add i18n translations
    pt_BR: Nome de Exibição
    ja_JP: ツール表示名
description:
  human:
    en_US: Description for human users
    zh_Hans: 人类用户的描述
  llm: Detailed description for AI models to understand when to use this tool
parameters:
  - name: parameter_name
    type: string                     # string, number, boolean, file
    required: true                   # or false for optional
    label:
      en_US: Parameter Display Name
      zh_Hans: 参数显示名称
    human_description:
      en_US: Description for users
      zh_Hans: 用户描述
    llm_description: Detailed parameter description for AI models
    form: llm                        # llm (AI extracts) or form (UI config)

  # Add more parameters as needed

extra:
  python:
    source: tools/tool-name.py       # Must match Python filename

Parameter Types:

•string - Text input
•number - Numeric input
•boolean - True/false
•file - File upload

Form Types:

•llm - AI extracts from user input (recommended for conversational use)
•form - User configures in UI (for admin settings)

2. Edit `tools/*.py`

Follow the exact Tool class pattern from the documentation:

python

from collections.abc import Generator
from typing import Any

from dify_plugin import Tool
from dify_plugin.entities.tool import ToolInvokeMessage

class YourToolName(Tool):
    """
    Tool for [description of what this tool does]
    """

    def _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]:
        """
        Invoke the tool with given parameters

        Args:
            tool_parameters: Dictionary of tool parameters

        Yields:
            ToolInvokeMessage: Messages to return to the user
        """
        try:
            # 1. Extract required parameters (use .get() with default)
            required_param = tool_parameters.get("param_name", "")

            # 2. Extract optional parameters (use .get() - returns None if missing)
            optional_param = tool_parameters.get("optional_param")

            # 3. Validate required parameters
            if not required_param:
                yield self.create_text_message("Error: Required parameter 'param_name' is missing.")
                return

            # 4. Implement your business logic here
            result = self._process_data(required_param, optional_param)

            # 5. Return results using appropriate message types

            # Text message (always visible to user)
            yield self.create_text_message(f"Result: {result}")

            # JSON message (structured data)
            yield self.create_json_message({
                "status": "success",
                "data": result
            })

            # Variable message (for workflow use)
            yield self.create_variable_message("result_variable", result)

            # Link message (clickable URLs)
            # yield self.create_link_message("https://example.com/result")

        except Exception as e:
            # Always include error handling
            yield self.create_text_message(f"Error: {str(e)}")

    def _process_data(self, required_param: str, optional_param: str = None) -> Any:
        """
        Helper method for business logic

        Args:
            required_param: Required input parameter
            optional_param: Optional input parameter

        Returns:
            Processed result
        """
        # Implement your logic here

        # Handle optional parameters
        if optional_param:
            result = f"Processed with both: {required_param}, {optional_param}"
        else:
            result = f"Processed with required only: {required_param}"

        return result

⚠️ CRITICAL RULES FROM DOCUMENTATION:

•ONE Tool class per .py file - Multiple classes will cause errors
•Exact method signature: _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]
•Use .get() for parameters - Prevents KeyError exceptions
•Return with yield - Not return
•Import from correct modules - Match documentation exactly

Message Types Available:

•create_text_message(text) - Display text to user
•create_json_message(dict) - Return structured data
•create_link_message(url) - Return clickable link
•create_variable_message(name, value) - Set workflow variable
•create_blob_message(data, name) - Return binary data/files

3. Edit `provider/*.yaml`

Add the new tool to the provider's tool list:

yaml

identity:
  author: author-name
  name: plugin-name
  label:
    en_US: Plugin Display Name
    zh_Hans: 插件显示名称
  description:
    en_US: Plugin description
    zh_Hans: 插件描述
  icon: icon.svg

# Only include if API keys or credentials are needed
credentials_for_provider:
  api_key:
    type: secret-input
    required: true
    label:
      en_US: API Key
      zh_Hans: API 密钥
    placeholder:
      en_US: Enter your API key
      zh_Hans: 输入您的 API 密钥
    help:
      en_US: Get your API key from https://example.com/api-keys
      zh_Hans: 从 https://example.com/api-keys 获取您的 API 密钥
    url: https://example.com/api-keys

tools:
  - tools/your-tool-name.yaml    # Add your tool here, it can be multiple tools in a single plugin

extra:
  python:
    source: provider/plugin-name.py

4. Edit `provider/*.py`

If credentials are needed, implement validation:

python

from typing import Any
from dify_plugin.entities.tool import ToolProviderCredentials

class YourPluginProvider:
    def _validate_credentials(self, credentials: dict[str, Any]) -> ToolProviderCredentials:
        """
        Validate provider credentials

        Args:
            credentials: Dictionary of credentials to validate

        Returns:
            ToolProviderCredentials object

        Raises:
            ToolProviderCredentialValidationError: If validation fails
        """
        try:
            # Extract credentials
            api_key = credentials.get("api_key")

            if not api_key:
                raise Exception("API key is required")

            # Validate by making a test API call
            # import requests
            # response = requests.get(
            #     "https://api.example.com/validate",
            #     headers={"Authorization": f"Bearer {api_key}"}
            # )
            # if response.status_code != 200:
            #     raise Exception("Invalid API key")

            return ToolProviderCredentials(credentials=credentials)

        except Exception as e:
            raise ToolProviderCredentialValidationError(str(e))

5. Update `manifest.yaml`

Complete all internationalization fields and metadata:

yaml

version: 0.0.1 # bump this for every new version 
type: plugin
author: author-name
name: plugin-name
label:
  en_US: Plugin Display Name
  zh_Hans: 插件显示名称
  pt_BR: Nome de Exibição do Plugin
  ja_JP: プラグイン表示名
description:
  en_US: Detailed description of what this plugin does
  zh_Hans: 该插件功能的详细描述
  pt_BR: Descrição detalhada do que este plugin faz
  ja_JP: このプラグインの機能の詳細な説明
icon: icon.svg
resource:
  memory: 268435456  # 256MB
  permission:
    network:
      enabled: true  # If API access needed
    storage:
      enabled: false
      size: 0
plugins:
  tools:
    - provider/plugin-name.yaml
meta:
  version: 0.0.1
  arch:
    - amd64
    - arm64
  runner:
    language: python
    version: "3.12"
    entrypoint: main
  minimum_dify_version: 1.9.0
created_at: 2025-11-04T00:00:00.000000+00:00
privacy: PRIVACY.md

6. Update `requirements.txt`

Add any Python package dependencies:

code

dify_plugin>=0.0.1 # you must use the dify_plugin version that the CLI added when initialized. 
requests>=2.31.0
# Add other dependencies as needed

PHASE 4: Test & Debug

Load Debugging Documentation:

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-debugging-logs.md

Add Logging to Your Tool:

According to the documentation, add logging imports and setup:

python

import logging
from dify_plugin.handlers import DifyPluginLogHandler

# Set up logging
logger = logging.getLogger(__name__)
logger.addHandler(DifyPluginLogHandler())

class YourTool(Tool):
    def _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]:
        logger.info(f"Tool invoked with parameters: {tool_parameters}")

        # Your implementation...

        logger.debug(f"Processing result: {result}")

        yield self.create_text_message(result)

PHASE 4.5: Remote Testing with Debug Key (MANDATORY Before Packaging)

⚠️ DO NOT PACKAGE without completing this phase.

This phase verifies the plugin works with a real Dify instance before distribution.

Objectives

•Test plugin with actual Dify remote host
•Verify functionality with debug key
•Catch integration issues before packaging
•Ensure proper logging and error handling

Prerequisites

Load debugging documentation:

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-debugging-logs.md

Steps

1. Request Dify Remote Connection Details

ASK the user for remote testing connection:

code

"To test this plugin with your Dify instance, I need:"

1. REMOTE_INSTALL_URL - e.g., https://your-dify.com or http://localhost:5003
2. Port (if not default) - usually 5003
3. REMOTE_INSTALL_KEY - get from Dify instance developer settings

Do you have a Dify instance available for testing?

If user doesn't have a Dify instance:

•Explain they can use local Dify installation
•Guide to set up local Dify (if needed)
•Or note that testing will be limited to code validation only

2. Configure Environment

Create/update .env file with remote connection:

bash

cd your-tool-directory

cat > .env << EOF
INSTALL_METHOD=remote
REMOTE_INSTALL_URL=debug.dify.ai:5003 # or user provided host
REMOTE_INSTALL_KEY=********-****-****-****-************
EOF

3. Start Plugin in Debug Mode

Run the plugin connected to remote host:

bash

cd your-tool-directory
python -m main

Expected console output:

code

INFO: Plugin loaded successfully
INFO: Connected to Dify remote host: https://your-dify-instance.com
INFO: Registered tools: [tool-name]
INFO: Waiting for invocations...

If errors appear:

•Check DIFY_REMOTE_HOST is accessible
•Verify DIFY_DEBUG_KEY is correct
•Check network connectivity
•Review error messages carefully

4. Test Tool Invocation from Dify

In Dify UI:

•Go to Tools section
•Find your plugin (should appear automatically)
•Try invoking the tool with test inputs
•Observe results

In console (watch logs):

code

INFO: Tool invoked: your-tool-name
DEBUG: Parameters: {"param1": "value1"}
DEBUG: Processing...
DEBUG: API call successful
INFO: Returned result to Dify

5. Test All Scenarios

Run comprehensive tests:

Test Case 1: Valid Input

code

Input: Normal, expected parameters
Expected: Success, correct output

Test Case 2: Missing Required Parameter

code

Input: Omit required parameter
Expected: Error message, graceful handling

Test Case 3: Invalid Input

code

Input: Wrong type or format
Expected: Validation error, helpful message

Test Case 4: API Integration (if applicable)

code

Input: Valid request requiring API call
Expected: Successful API call, correct data returned

Test Case 5: Error Conditions

code

Input: Trigger expected errors (API timeout, invalid credentials, etc.)
Expected: Proper error handling, helpful messages

Test Case 6: OAuth Flow (if applicable)

code

Action: Complete OAuth authorization
Expected: Token received, API calls work with token

Expected Output:

•Plugin should start without errors
•You should see log output
•Tool should be ready to receive invocations
•Guide the user to test it in the dify environment while the debug script runs.

If Errors Occur:

•LOAD references/troubleshooting.md
•Find the error pattern
•Apply the documented solution
•Re-test

Common Errors:

Error	Cause	Solution
`Multiple subclasses of Tool in file.py`	Multiple Tool classes in one file	Keep only one Tool class per .py file, move others to new files
`ImportError: cannot import name 'X'`	Import name doesn't match definition	Check spelling, case, underscores in import statements
`KeyError: 'parameter_name'`	Parameter accessed without checking	Use `.get()` method: `param = tool_parameters.get("name", "")`
`ToolProviderCredentialValidationError`	Credential validation failed	Check API key format, test API endpoint, verify credentials

Debug Checklist:

• One Tool class per .py file
• Exact import statements from docs
• Using .get() for all parameters
• Method signature matches docs exactly
• YAML files have correct syntax
• All required fields present in YAML
• Credentials properly validated

6. Verify Debug Logging

Check that logs show:

Example good logging:

python

logger.info(f"Tool invoked: {tool_name}")
logger.debug(f"Parameters: {tool_parameters}")
logger.debug("Calling API endpoint...")
logger.debug(f"API response status: {response.status_code}")
logger.info("Successfully processed request")

7. Debug Issues

If tool doesn't work as expected:

•Check console logs for errors
•Verify parameters are extracted correctly
•Test API calls independently
•Check credential validation
•Load references/troubleshooting.md for common issues

Common remote testing issues:

Issue	Cause	Solution
Plugin doesn't appear	Registration failed	Check manifest.yaml, restart plugin
Connection refused	Wrong host URL	Verify DIFY_REMOTE_HOST
Unauthorized	Invalid debug key	Check DIFY_DEBUG_KEY
Tool fails	Parameter handling	Verify .get() usage, check logs
API errors	Credential issues	Test API key separately

8. User Confirmation

Before proceeding to packaging, ask user:

code

"I've tested the plugin with your Dify instance. Results:

✅ Plugin loaded successfully
✅ Tool appears in Dify UI
✅ Test invocations working
✅ [List specific test results]

Does everything work as expected? Any issues or adjustments needed?"

Wait for user confirmation before packaging.

4. Verify requirements.txt Contains Latest dify_plugin

⚠️ CRITICAL CHECK: Verify the dify_plugin version that CLI generated.

The Dify CLI always creates requirements.txt with the latest dify_plugin version.

bash

cat your-tool-name/requirements.txt

Check what version was generated:

code

dify_plugin>=X.X.X

DO NOT override this version. The CLI uses the latest compatible version.

Note the version for reference:

•This is the version your plugin will use
•Keep this version in requirements.txt
•Only add additional dependencies you need

Example:

code

dify_plugin>=2.4.2    # Generated by CLI - KEEP THIS
requests>=2.31.0       # Add if you need requests
pyyaml>=6.0           # Add if you need yaml

Success Criteria (All Must Pass)

• Plugin connects to remote Dify instance
• Debug key configured and accepted
• Tool appears in Dify UI
• Tool can be invoked successfully
• All test scenarios pass
• Logs show clean execution
• No errors in remote testing
• User confirms functionality correct
• Ready to package

⚠️ If ANY criterion fails:

•DO NOT proceed to packaging
•Debug the issue using troubleshooting.md
•Fix and re-test
•Only package when ALL tests pass

PHASE 5: Package & Publish

Load Packaging Documentation:

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-tool-plugin.md
# Read the "Packaging the Plugin" section

Package the Plugin:

bash

dify plugin package ./your-tool-directory

This creates a .difypkg file in the current directory.

Expected Output:

code

✓ plugin packaged successfully, output path: your-tool-name.difypkg

Verify Package:

bash

ls -lh *.difypkg

The file should exist and have a reasonable size (typically 10-100 KB for simple plugins).

Publishing (Optional):

If the user wants to publish to the Dify marketplace:

•Visit the Dify plugin marketplace
•Create an account if needed
•Upload the .difypkg file
•Fill in marketplace metadata
•Submit for review

Guide the user through this process if requested.

OAuth Implementation Guide

If the tool requires OAuth authentication (e.g., GitHub, Google, Slack):

⚠️ MANDATORY: Load the complete OAuth documentation BEFORE implementing

bash

curl -s https://docs.dify.ai/plugin-dev-en/0222-tool-oauth.md

OAuth Implementation Steps:

•Define OAuth Schema in provider/*.yaml:

yaml

oauth_schema:
  client:
    - name: client_id
      type: string
      required: true
      label:
        en_US: Client ID
    - name: client_secret
      type: secret-input
      required: true
      label:
        en_US: Client Secret
  authorization:
    url: https://provider.com/oauth/authorize
    scopes:
      - scope1
      - scope2
  token:
    url: https://provider.com/oauth/token

•Implement OAuth Methods in provider/*.py:

python

def get_authorization_url(self, credentials: dict) -> str:
    """Return OAuth authorization URL"""
    pass

def validate_oauth_callback(self, credentials: dict, state: str, code: str) -> dict:
    """Exchange code for access token"""
    pass

•Access Tokens in Tools:

python

def _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]:
    # Access token is available in runtime
    access_token = self.runtime.credentials.get("access_token")

    # Use token in API calls
    headers = {"Authorization": f"Bearer {access_token}"}

Refer to the OAuth documentation for complete implementation details.

Best Practices (From Official Documentation)

ALWAYS:

•Load official documentation BEFORE writing any code
•Follow exact syntax and structure from the docs
•Use one Tool class per .py file
•Use .get() method for accessing parameters
•Include comprehensive error handling
•Add logging for debugging
•Test thoroughly before packaging
•Document all methods and classes
•Validate credentials properly

NEVER:

•Guess at syntax or structure
•Skip mandatory documentation loading
•Put multiple Tool classes in one file
•Access parameters without .get() or validation
•Use local file I/O operations (serverless environment constraint)
•Assume parameters exist without checking
•Package without testing first
•Skip error handling

Security Considerations:

•Always validate and sanitize user inputs
•Never log sensitive data (API keys, passwords)
•Use environment variables for credentials
•Validate credentials before use
•Handle API errors gracefully

Progress Tracking

Throughout the development process, keep the user informed:

•Current Phase: Tell the user which phase you're in
•Completed Steps: Show what has been accomplished
•Next Actions: Explain what will happen next
•User Input Needed: Ask for clarification when needed
•Problems Encountered: Report any issues and solutions

Example Progress Update:

code

✅ Phase 1 Complete: Requirements gathered
✅ Phase 2 Complete: Project initialized
🔄 Phase 3 In Progress: Implementing tool (60% done)
   ✅ YAML configuration complete
   ✅ Tool class structure created
   🔄 Adding API integration
   ⏳ Error handling pending
   ⏳ Logging setup pending
⏳ Phase 4 Pending: Testing & debugging
⏳ Phase 5 Pending: Packaging

Reference Quick Access

Load these reference files when you need specific information:

•references/doc-map.md - Complete map of what each official doc contains
•references/workflow.md - Detailed 5-phase workflow
•references/cli-commands.md - Dify CLI command reference
•references/troubleshooting.md - Common errors and solutions
•references/examples.md - Real-world plugin examples

Helper Script:

Use the fetch script to quickly retrieve official docs:

bash

bash scripts/fetch_doc.sh tool        # Fetch tool-plugin.md
bash scripts/fetch_doc.sh oauth       # Fetch tool-oauth.md
bash scripts/fetch_doc.sh debug       # Fetch debugging-logs.md
bash scripts/fetch_doc.sh init        # Fetch initialize-development-tools.md

Summary

This skill guides you through a structured 5-phase workflow:

•Setup & Planning - Gather requirements, verify CLI
•Initialize Project - Create plugin structure with CLI
•Implement Tool - Write YAML configs and Python code
•Test & Debug - Run locally, fix issues, add logging
•Package & Publish - Create .difypkg file, optionally publish

Key Success Factors:

•Always load documentation before coding
•Follow official patterns exactly
•Test thoroughly before packaging
•Handle errors gracefully
•Keep the user informed of progress

The result will be a production-ready Dify tool plugin that follows best practices and official guidelines.

Dify Tool Plugin Developer

When to Use This Skill

Agent Responsibilities

Critical Rule: MANDATORY Documentation Loading

Documentation Fetching

Development Workflow

PHASE 1: Setup & Planning

Option 2: Use Helper Script (Recommended)

PHASE 1.5: Load Required Documentation (MANDATORY)

Required Documentation (ALWAYS LOAD)

Conditional Documentation (Load if needed)

How to Determine What to Load

PHASE 2: Initialize Project

PHASE 3: Implement Tool

1. Edit tools/*.yaml

2. Edit tools/*.py

3. Edit provider/*.yaml

4. Edit provider/*.py

5. Update manifest.yaml

6. Update requirements.txt

PHASE 4: Test & Debug

PHASE 4.5: Remote Testing with Debug Key (MANDATORY Before Packaging)

Objectives

Prerequisites

Steps

4. Verify requirements.txt Contains Latest dify_plugin

Success Criteria (All Must Pass)

PHASE 5: Package & Publish

OAuth Implementation Guide

Best Practices (From Official Documentation)

Progress Tracking

Reference Quick Access

Summary

1. Edit `tools/*.yaml`

2. Edit `tools/*.py`

3. Edit `provider/*.yaml`

4. Edit `provider/*.py`

5. Update `manifest.yaml`

6. Update `requirements.txt`