{
  "schemaVersion": "1.0",
  "item": {
    "slug": "diataxis-writing",
    "name": "Diataxis Writing",
    "source": "tencent",
    "type": "skill",
    "category": "内容创作",
    "sourceUrl": "https://clawhub.ai/amumulam/diataxis-writing",
    "canonicalUrl": "https://clawhub.ai/amumulam/diataxis-writing",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/diataxis-writing",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=diataxis-writing",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "CHANGELOG.md",
      "README.md",
      "SKILL.md",
      "checklist/checklist-explanation.md",
      "checklist/checklist-how-to.md",
      "checklist/checklist-reference.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-23T16:43:11.935Z",
      "expiresAt": "2026-04-30T16:43:11.935Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=4claw-imageboard",
        "contentDisposition": "attachment; filename=\"4claw-imageboard-1.0.1.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/diataxis-writing"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/diataxis-writing",
    "agentPageUrl": "https://openagent3.xyz/skills/diataxis-writing/agent",
    "manifestUrl": "https://openagent3.xyz/skills/diataxis-writing/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/diataxis-writing/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Quick Start",
        "body": "When creating or refactoring documentation:"
      },
      {
        "title": "Pre-Writing Questions (Must Ask)",
        "body": "Before starting, ask the user:\n\nLanguage Preference: \"What language should this document be written in?\"\n\nEnglish / 中文 / Other\n\n\n\nOutput Method: \"After completion, how would you like to output this document?\"\n\nChat message (default)\nFeishu document (via MCP/mcporter)\nLocal Markdown file\nGitHub repository\nOther platforms"
      },
      {
        "title": "Tool Availability Check (After User Selection)",
        "body": "After user selects output method, automatically check tool availability:\n\n# Run auto-detection (script is in ./scripts/ relative to this skill)\npython3 scripts/output-handler.py --detect\n\nCheck results:\n\n✅ Tool available → Proceed with selected output method\n⚠️ Tool not available → Inform user and suggest alternatives\n\nFor Feishu output via MCP:\n\nCheck if mcporter is installed\nCheck if MCP feishu server is configured (typically in /root/config/mcporter.json or ~/.mcporter/mcporter.json)\nTest connection to Feishu MCP server\n\nIf tool not available:\n\nInform user: \"Selected output method [X] is not available\"\nSuggest alternatives: \"Available options: [list]\"\nAsk user to confirm alternative or configure tool"
      },
      {
        "title": "Writing Workflow",
        "body": "After confirming language, output preference, and tool availability:\n\nIdentify User Needs - Use the Diataxis Compass to determine document type\nSelect Template - Choose the corresponding template from templates/\nApply Checklist - Use the corresponding checklist during writing\nQuality Assessment - Use the quality framework to evaluate the final draft\nExecute Output - Output using the user's chosen method and language"
      },
      {
        "title": "Four Documentation Types",
        "body": "Diataxis identifies four fundamentally different documentation types, corresponding to four user needs:\n\nTypeUser NeedDocument PurposeKey CharacteristicsTutorialAcquire skills (study)Provide learning experiencePractice-oriented, minimize explanation, concrete stepsHow-to GuideApply skills (work)Help complete tasksGoal-oriented, assume competence, handle real scenariosReferenceApply skills (work)Describe technical factsNeutral description, accurate and complete, structuredExplanationAcquire skills (study)Provide understanding contextDiscursive, allows opinions, provides context"
      },
      {
        "title": "Type Details",
        "body": "Tutorial: references/four-types.md#Tutorial\nHow-to Guide: references/four-types.md#How-to Guide\nReference: references/four-types.md#Reference\nExplanation: references/four-types.md#Explanation"
      },
      {
        "title": "Using the Diataxis Compass",
        "body": "When unsure about document type, use the compass tool: references/compass.md\n\nAsk two questions:\n\nContent Type: Is it action guidance (action) or cognitive knowledge (cognition)?\nUser State: Is the user acquiring skills (acquisition/study) or applying skills (application/work)?"
      },
      {
        "title": "Use Case 1: Troubleshooting Records → How-to Guide or Explanation",
        "body": "Troubleshooting records typically belong to:\n\nHow-to Guide: If it's step-by-step guidance on \"how to solve X problem\"\nExplanation: If it's principle analysis on \"why X problem occurred\"\n\nTemplate: templates/template-troubleshooting.md"
      },
      {
        "title": "Use Case 2: Experience Summary → How-to Guide or Explanation",
        "body": "Best Practices: How-to Guide (guidance on how to do things correctly)\nLessons Learned: Explanation (explaining why certain approaches are wrong)\n\nTemplate: templates/template-best-practices.md"
      },
      {
        "title": "Use Case 3: Learning Notes → Tutorial or Explanation",
        "body": "Learning Notes: Tutorial (if containing practical steps)\nTheory Summary: Explanation (if conceptual understanding)\n\nTemplate: templates/template-learning-notes.md"
      },
      {
        "title": "Use Case 4: Exploratory Sharing → Explanation",
        "body": "Technical exploration, experiment records, and comparative analysis typically belong to Explanation.\n\nTemplate: templates/template-exploration.md"
      },
      {
        "title": "Checklists",
        "body": "Use checklists during and after writing:\n\nTutorial: checklist/checklist-tutorial.md\nHow-to: checklist/checklist-how-to.md\nReference: checklist/checklist-reference.md\nExplanation: checklist/checklist-explanation.md"
      },
      {
        "title": "Quality Assessment",
        "body": "Use the Functional Quality and Deep Quality framework: references/quality-framework.md"
      },
      {
        "title": "Functional Quality",
        "body": "Accuracy, completeness, consistency, usability, precision"
      },
      {
        "title": "Deep Quality",
        "body": "Flow, fitting human needs, beauty, anticipating user needs"
      },
      {
        "title": "Common Mistakes",
        "body": "Avoid the following error patterns: references/common-mistakes.md\n\nType Conflation - Mixing Reference content into Tutorial\nMisplacement - Writing Explanation as Tutorial\nBoundary Blur - Mixing too much explanation into How-to\nStructural Misalignment - Reference not reflecting product architecture"
      },
      {
        "title": "Language Style",
        "body": "Four types use different language styles: references/writing-language.md\n\nTutorial: \"We will...\", \"Notice...\", \"Now do X...\"\nHow-to: \"If you want X, do Y\", \"Refer to X documentation for complete options\"\nReference: \"X inherits Y\", \"Subcommands: a, b, c\", \"Must use X\"\nExplanation: \"The reason for X is...\", \"W is better than Z because...\""
      },
      {
        "title": "Output Methods",
        "body": "After completing the document, output using the user's chosen method:"
      },
      {
        "title": "Available Output Methods",
        "body": "Chat Message - Display directly in conversation (default)\nFeishu Document - Create/update Feishu document via MCP/mcporter (requires MCP feishu server)\nLocal Markdown - Save as .md file (built-in support)\nGitHub Repo - Commit to code repository (requires MCP github or git)\nOther Platforms - User provides platform and MCP capabilities\n\nImportant: For Feishu output, always use MCP/mcporter method, NOT channel tools."
      },
      {
        "title": "Detect Available Tools",
        "body": "Use scripts/output-handler.py to auto-detect (script is in ./scripts/ relative to this skill file):\n\npython3 scripts/output-handler.py --detect"
      },
      {
        "title": "Tool Availability Check",
        "body": "After user selects output method, check if tool is available:\n\nRun output-handler.py --detect\nCheck if selected tool is configured and available\nIf not available:\n\nInform user: \"Selected output method [X] is not available\"\nSuggest alternatives from available tools list\nAsk user to confirm alternative"
      },
      {
        "title": "Choose Output Method",
        "body": "Must ask user: \"Document completed, how would you like to output?\"\n\nBased on user selection:\n\nChat → Reply directly\nFeishu (MCP) → Use mcporter to call Feishu MCP server\nnode /path/to/mcporter/dist/cli.js call feishu doc.create '{\"title\":\"...\", \"content\":\"...\"}'\n# Note: mcporter path varies by installation, common paths:\n# - ~/.npm/_npx/*/node_modules/mcporter/dist/cli.js\n# - Or use: npx mcporter call feishu doc.create ...\n\n\nLocal → Call write tool or output-handler.py --output local\nGitHub → Call output-handler.py --output github\nOther → Ask user to provide MCP server information"
      },
      {
        "title": "Language Considerations",
        "body": "Output in the user's chosen language:\n\nIf English → Output in English\nIf Chinese (中文) → Output in Chinese\nIf other → Confirm translation capabilities"
      },
      {
        "title": "Output Platform Details",
        "body": "Complete platform list and configuration methods: references/output-platforms.md\n\nPlatformRequired ToolsConfiguration DifficultyUse CaseChatNone-Quick replyFeishu (MCP)MCP feishu serverMediumTeam collaborationLocal MDwriteLowPersonal knowledgeGitHubMCP github/gitMediumTech blogNotionMCP notionMediumKnowledge baseGoogle DocsMCP googleHighGoogle ecosystem"
      },
      {
        "title": "Theoretical Framework",
        "body": "Complete Diataxis theory:\n\nMap Model: references/map.md\nTheoretical Foundations: references/four-types.md\nQuality Theory: references/quality-framework.md"
      },
      {
        "title": "Using Scripts (Optional)",
        "body": "Use the diagnosis script to automatically identify document types (script is in ./scripts/ relative to this skill):\n\npython3 scripts/diagnose.py <document content or file path>\n\nSkill Version: 1.0\nTheory Source: https://diataxis.fr\nAuthor: Zhua Zhua (Created for Master)"
      }
    ],
    "body": "Diátaxis Documentation Framework Practice\nQuick Start\n\nWhen creating or refactoring documentation:\n\nPre-Writing Questions (Must Ask)\n\nBefore starting, ask the user:\n\nLanguage Preference: \"What language should this document be written in?\"\n\nEnglish / 中文 / Other\n\nOutput Method: \"After completion, how would you like to output this document?\"\n\nChat message (default)\nFeishu document (via MCP/mcporter)\nLocal Markdown file\nGitHub repository\nOther platforms\nTool Availability Check (After User Selection)\n\nAfter user selects output method, automatically check tool availability:\n\n# Run auto-detection (script is in ./scripts/ relative to this skill)\npython3 scripts/output-handler.py --detect\n\n\nCheck results:\n\n✅ Tool available → Proceed with selected output method\n⚠️ Tool not available → Inform user and suggest alternatives\n\nFor Feishu output via MCP:\n\nCheck if mcporter is installed\nCheck if MCP feishu server is configured (typically in /root/config/mcporter.json or ~/.mcporter/mcporter.json)\nTest connection to Feishu MCP server\n\nIf tool not available:\n\nInform user: \"Selected output method [X] is not available\"\nSuggest alternatives: \"Available options: [list]\"\nAsk user to confirm alternative or configure tool\nWriting Workflow\n\nAfter confirming language, output preference, and tool availability:\n\nIdentify User Needs - Use the Diataxis Compass to determine document type\nSelect Template - Choose the corresponding template from templates/\nApply Checklist - Use the corresponding checklist during writing\nQuality Assessment - Use the quality framework to evaluate the final draft\nExecute Output - Output using the user's chosen method and language\nFour Documentation Types\n\nDiataxis identifies four fundamentally different documentation types, corresponding to four user needs:\n\nType\tUser Need\tDocument Purpose\tKey Characteristics\nTutorial\tAcquire skills (study)\tProvide learning experience\tPractice-oriented, minimize explanation, concrete steps\nHow-to Guide\tApply skills (work)\tHelp complete tasks\tGoal-oriented, assume competence, handle real scenarios\nReference\tApply skills (work)\tDescribe technical facts\tNeutral description, accurate and complete, structured\nExplanation\tAcquire skills (study)\tProvide understanding context\tDiscursive, allows opinions, provides context\nType Details\nTutorial: references/four-types.md#Tutorial\nHow-to Guide: references/four-types.md#How-to Guide\nReference: references/four-types.md#Reference\nExplanation: references/four-types.md#Explanation\nUsing the Diataxis Compass\n\nWhen unsure about document type, use the compass tool: references/compass.md\n\nAsk two questions:\n\nContent Type: Is it action guidance (action) or cognitive knowledge (cognition)?\nUser State: Is the user acquiring skills (acquisition/study) or applying skills (application/work)?\nCommon Use Cases\nUse Case 1: Troubleshooting Records → How-to Guide or Explanation\n\nTroubleshooting records typically belong to:\n\nHow-to Guide: If it's step-by-step guidance on \"how to solve X problem\"\nExplanation: If it's principle analysis on \"why X problem occurred\"\n\nTemplate: templates/template-troubleshooting.md\n\nUse Case 2: Experience Summary → How-to Guide or Explanation\nBest Practices: How-to Guide (guidance on how to do things correctly)\nLessons Learned: Explanation (explaining why certain approaches are wrong)\n\nTemplate: templates/template-best-practices.md\n\nUse Case 3: Learning Notes → Tutorial or Explanation\nLearning Notes: Tutorial (if containing practical steps)\nTheory Summary: Explanation (if conceptual understanding)\n\nTemplate: templates/template-learning-notes.md\n\nUse Case 4: Exploratory Sharing → Explanation\n\nTechnical exploration, experiment records, and comparative analysis typically belong to Explanation.\n\nTemplate: templates/template-exploration.md\n\nChecklists\n\nUse checklists during and after writing:\n\nTutorial: checklist/checklist-tutorial.md\nHow-to: checklist/checklist-how-to.md\nReference: checklist/checklist-reference.md\nExplanation: checklist/checklist-explanation.md\nQuality Assessment\n\nUse the Functional Quality and Deep Quality framework: references/quality-framework.md\n\nFunctional Quality\nAccuracy, completeness, consistency, usability, precision\nDeep Quality\nFlow, fitting human needs, beauty, anticipating user needs\nCommon Mistakes\n\nAvoid the following error patterns: references/common-mistakes.md\n\nType Conflation - Mixing Reference content into Tutorial\nMisplacement - Writing Explanation as Tutorial\nBoundary Blur - Mixing too much explanation into How-to\nStructural Misalignment - Reference not reflecting product architecture\nLanguage Style\n\nFour types use different language styles: references/writing-language.md\n\nTutorial: \"We will...\", \"Notice...\", \"Now do X...\"\nHow-to: \"If you want X, do Y\", \"Refer to X documentation for complete options\"\nReference: \"X inherits Y\", \"Subcommands: a, b, c\", \"Must use X\"\nExplanation: \"The reason for X is...\", \"W is better than Z because...\"\nOutput Methods\n\nAfter completing the document, output using the user's chosen method:\n\nAvailable Output Methods\nChat Message - Display directly in conversation (default)\nFeishu Document - Create/update Feishu document via MCP/mcporter (requires MCP feishu server)\nLocal Markdown - Save as .md file (built-in support)\nGitHub Repo - Commit to code repository (requires MCP github or git)\nOther Platforms - User provides platform and MCP capabilities\n\nImportant: For Feishu output, always use MCP/mcporter method, NOT channel tools.\n\nDetect Available Tools\n\nUse scripts/output-handler.py to auto-detect (script is in ./scripts/ relative to this skill file):\n\npython3 scripts/output-handler.py --detect\n\nTool Availability Check\n\nAfter user selects output method, check if tool is available:\n\nRun output-handler.py --detect\nCheck if selected tool is configured and available\nIf not available:\nInform user: \"Selected output method [X] is not available\"\nSuggest alternatives from available tools list\nAsk user to confirm alternative\nChoose Output Method\n\nMust ask user: \"Document completed, how would you like to output?\"\n\nBased on user selection:\n\nChat → Reply directly\nFeishu (MCP) → Use mcporter to call Feishu MCP server\nnode /path/to/mcporter/dist/cli.js call feishu doc.create '{\"title\":\"...\", \"content\":\"...\"}'\n# Note: mcporter path varies by installation, common paths:\n# - ~/.npm/_npx/*/node_modules/mcporter/dist/cli.js\n# - Or use: npx mcporter call feishu doc.create ...\n\nLocal → Call write tool or output-handler.py --output local\nGitHub → Call output-handler.py --output github\nOther → Ask user to provide MCP server information\nLanguage Considerations\n\nOutput in the user's chosen language:\n\nIf English → Output in English\nIf Chinese (中文) → Output in Chinese\nIf other → Confirm translation capabilities\nOutput Platform Details\n\nComplete platform list and configuration methods: references/output-platforms.md\n\nPlatform\tRequired Tools\tConfiguration Difficulty\tUse Case\nChat\tNone\t-\tQuick reply\nFeishu (MCP)\tMCP feishu server\tMedium\tTeam collaboration\nLocal MD\twrite\tLow\tPersonal knowledge\nGitHub\tMCP github/git\tMedium\tTech blog\nNotion\tMCP notion\tMedium\tKnowledge base\nGoogle Docs\tMCP google\tHigh\tGoogle ecosystem\nTheoretical Framework\n\nComplete Diataxis theory:\n\nMap Model: references/map.md\nTheoretical Foundations: references/four-types.md\nQuality Theory: references/quality-framework.md\nUsing Scripts (Optional)\n\nUse the diagnosis script to automatically identify document types (script is in ./scripts/ relative to this skill):\n\npython3 scripts/diagnose.py <document content or file path>\n\n\nSkill Version: 1.0\nTheory Source: https://diataxis.fr\nAuthor: Zhua Zhua (Created for Master)"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/amumulam/diataxis-writing",
    "publisherUrl": "https://clawhub.ai/amumulam/diataxis-writing",
    "owner": "amumulam",
    "version": "1.2.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/diataxis-writing",
    "downloadUrl": "https://openagent3.xyz/downloads/diataxis-writing",
    "agentUrl": "https://openagent3.xyz/skills/diataxis-writing/agent",
    "manifestUrl": "https://openagent3.xyz/skills/diataxis-writing/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/diataxis-writing/agent.md"
  }
}