跳到主内容
智客 ZICQ

技能库 智客分类:文档办公 documentation

Documentation

按照Diataxis框架创建、结构和审查技术文件(教程、指南、参考和解释页)。 当用户需要写入或重组docs时使用,构建一个教程 vs. a 如何引导、构建参考文件或API文档、创建解释页、在Diataxis文档类型中选择,或改进现有的文档结构。 触发词包括:文档结构,Diátaxis,教程与如何向导,组织道克,用户向导,参考道克,技术写作.

1725 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

按照Diataxis框架创建、结构和审查技术文件(教程、指南、参考资料和解释页)

何时用

当您需要按照 Diataxis 框架创建、审查或改进技术文档时使用此技能 。 例如:

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:When to use、Instructions、Step 1 — Identify the documentation type、Step 2 — Apply type-specific patterns、Step 3 — Maintain separation and integration、Step 4 — Validate before delivering。 其中含规范建议的小节:分步指令。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing.

When to useInstructionsStep 1 — Identify the documentation typeStep 2 — Apply type-specific patternsStep 3 — Maintain separation and integrationStep 4 — Validate before delivering

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
documentation
description
Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「documentation」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-3a8f4694d920c5d5-%E6%96%87%E6%A1%A3.html
请存为 .cursor/skills/documentation/SKILL.md 或 .claude/skills/documentation/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/mcollina/skills' --list

npx skills add 'https://github.com/mcollina/skills' --skill 'documentation'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版

name: documentation description: "Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing." metadata: tags: documentation, technical-writing, tutorials, guides, reference, diataxis

When to use

Use this skill when you need to create, review, or improve technical documentation following the Diátaxis framework. Examples include:

  • Creating user guides
  • API documentation
  • Tutorial content
  • Restructuring existing documentation to better serve different user needs and contexts

Instructions

Organize documentation into four distinct types — tutorials, how-to guides, reference material, and explanations — each serving different user needs and contexts.

Always ask clarifying questions about the user's context, audience, and goals before creating documentation.


Step 1 — Identify the documentation type

Use the following decision checklist based on user signals:

| User signal | Documentation type | |---|---| | "I'm new to X and want to learn it" / "walk me through" | Tutorial | | "How do I…?" / "I need to accomplish X" | How-to guide | | "What are the parameters/options/syntax for X?" | Reference | | "Why does X work this way?" / "Help me understand X" | Explanation |

Quick decision tree:

  • Is the user learning by doing for the first time? → Tutorial
  • Do they need to solve a specific problem they already understand? → How-to guide
  • Do they need technical facts to look up? → Reference
  • Do they want conceptual background? → Explanation

Step 2 — Apply type-specific patterns

Tutorials (learning-oriented)

  • Title pattern: Start with a verb — "Build your first X", "Create a Y from scratch"
  • Structure: Goal → Prerequisites → Numbered steps → Immediate verifiable result at each step → Final outcome
  • Minimise explanation; maximise doing
  • Every step must produce a visible, testable result
  • Validation: A beginner must be able to complete the tutorial without external help

Example intro:

"In this tutorial, you will build a simple REST API using Express. By the end, you will have a running server that responds to GET requests. No prior Express experience is needed."


How-to guides (problem-oriented)

  • Title pattern: Frame as a task — "How to configure X", "How to deploy Y to Z"
  • Structure: Goal statement → Assumptions/prerequisites → Numbered steps → Expected result
  • Assume baseline knowledge; skip conceptual explanations
  • Allow for variation; note alternatives where they exist
  • Validation: An experienced user can complete the task without confusion or backtracking

Example intro:

"This guide shows how to add JWT authentication to an existing Express app. It assumes you have a working Express server and basic familiarity with middleware."


Reference (information-oriented)

  • Title pattern: Name the thing — "Configuration options", "API endpoints", "CLI flags"
  • Structure: Consistent repeatable format per entry (name → type → default → description → example)
  • State facts; avoid instruction beyond minimal usage examples
  • Keep current; version-stamp if needed
  • Validation: A user can look up a specific fact in under 30 seconds without reading surrounding content

Example entry:

timeout (integer, default: 5000) Maximum time in milliseconds to wait for a response before the request fails. Example: { timeout: 3000 }


Explanations (understanding-oriented)

  • Title pattern: Frame as a concept — "How X works", "Understanding Y", "Why Z is designed this way"
  • Structure: Context → Core concept → Alternatives/trade-offs → Higher-level perspective
  • Avoid step-by-step instruction or technical specification
  • Validation: After reading, the user can explain the concept in their own words and understands the rationale behind design decisions

Example intro:

"Authentication and authorisation are often confused. This page explains the distinction, why both matter, and how common patterns (sessions, tokens, OAuth) approach each concern differently."


Step 3 — Maintain separation and integration

  • Keep each document a single type — don't mix tutorial steps with reference tables or conceptual digressions
  • Cross-link between types: a tutorial can link to the relevant reference page; a how-to guide can link to an explanation for background
  • Use consistent headings and terminology across all types so users can navigate the full documentation system

Step 4 — Validate before delivering

| Type | Validation check | |---|---| | Tutorial | Can a beginner complete it end-to-end without external help? | | How-to guide | Does it solve the stated problem for an experienced user? | | Reference | Can the user find a specific fact in under 30 seconds? | | Explanation | Does the user understand the why, not just the what? |

相关技能

文档办公

Ontology

为结构化的代理内存和可堆肥技能所打入的知识图. 在创建/征服实体(Person, project, Task, Evention, Document)时使用,链接相关对象,强制约束,规划多步动作作为图变,或技能需要共享状态时使用. 触发到"记住","我知道什么","链接X到Y",…

文档办公

Nano Pdf

使用纳米-pdf CLI编辑带有自然语言指令的PDF.

文档办公

Word / DOCX

创建,检查,并编辑有可靠样式的Microsoft Word文档和DOCX文件,编号,跟踪更改,表格,章节,并进行相容性检查. 当 (1) 任务涉及 Word 或 ".docx " 时使用; (2) 文件包括跟踪的更改,评论,字段,表格,模板,或页面布局限制; (3) 文档必须在不…

文档办公

Api Gateway

通过 Maton 网关调用第三方 API, 它为用户已经连接的应用程序注入证书 。 当用户命名一个连接的应用程序和其中的具体行动时使用此技能——读取一个邮箱,查询一个CMM,归档一个问题,更新一个电子表格,通过一个连接的搜索或刮取提供者运行一个查询. 每一次通话都到用户连接的应用…