跳到主内容
智客 ZICQ

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

Document

运行/文件`pr' |`changlog' |`release-note ' |`profatural' (或请它写给面临改变的人取道。 从真正的承诺和diff的草稿,写到正确的地方。 不写代码、测试或规格.

2617 安装量

官方网址:skills.sh

技能介绍

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

做什么

运行/文件`pr' |`changlog' |`release-note ' |`profatural' (或请它写给面临改变的人取道。 从真正的承诺和diff的草稿,写到正确的地方。 不写代码、测试或规格.

何时用

官方 description 未单独写出 Use when。按规范,代理会在用户任务与这段 description 的关键词匹配时激活本技能。

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Output style (plain words, no dashes, no hyphens)、What this skill does、Artifact ownership、Portability (any OS, any agent)、Execution、1. Determine the document type。

文件分析

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

官方 description(原文)

Run /document `pr` | `changelog` | `release-note` | `postmortem` (or let it ask) to write the human facing prose about a change. Drafts from the real commits and diff, writing to the right place. Does not write code, tests, or specs.

Output style (plain words, no dashes, no hyphens)What this skill doesArtifact ownershipPortability (any OS, any agent)Execution1. Determine the document type2. Gather the source materialbase branch: use `main` if it exists, otherwise `master`current branchpr / changelog: the branch change set (BASE = the base branch above)release-note: needs tags. List them; if there are none, fall back gracefully (treat as NO_TAGS).3. Write the document (main thread)

· allowed-tools:Bash, Read, Grep, Glob, Write, Edit, Agent, AskUserQuestion

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
document
description
Run /document `pr` | `changelog` | `release-note` | `postmortem` (or let it ask) to write the human facing prose about a change. Drafts from the real commits and diff, writing to the right place. Does not write code, tests, or specs.
allowed-tools
Bash, Read, Grep, Glob, Write, Edit, Agent, AskUserQuestion实验字段,支持情况取决于客户端;字段声明本身不会授予工具权限。
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

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

安装这个技能

Skills CLI ↗

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

交给 Agent 安装

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

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

GitHub 完整包 ↗

终端安装 · Skills CLI

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

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

npx skills add 'https://github.com/jsmastery-pro/skills' --skill 'document'

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

阅读排版
--- name: document allowed-tools: Bash, Read, Grep, Glob, Write, Edit, Agent, AskUserQuestion description: "Run /document `pr` | `changelog` | `release-note` | `postmortem` (or let it ask) to write the human facing prose about a change. Drafts from the real commits and diff, writing to the right place. Does not write code, tests, or specs." --- ## Output style (plain words, no dashes, no hyphens) Write everything this skill produces, files and messages alike, in plain simple language. Talk to the reader as `you`, warm and direct like a colleague, and present every step as a recommendation they may run or skip, never an order. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write `read only`, not `read-only`. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever. ## What this skill does **Your role:** the technical writer who writes from the record, not from imagination, and for the reader, not the author. Every sentence traces to something that actually happened (a commit, a diff, an incident fact you were given), and every document is pitched at whoever has to act on it (audience column below). You never invent a timeline entry, a cause, or a change that isn't in the source. Generates one of four document types from the real change history. The main thread writes the document itself; the only thing it may offload is reading, and only for a very large diff, to a read only `scout` subagent on the cheapest model (Claude Code: `haiku`): | Type | Source | Audience | Output | |---|---|---|---| | `pr` | branch commits + diff vs base | reviewers | PR title + body (chat; optionally `gh pr` create/edit) | | `changelog` | merged change | developers | entry appended to `CHANGELOG.md` (Keep a Changelog) | | `release-note` | a tag/version range | end users | `docs/releases/.md` (or chat) | | `postmortem` | an incident (described by the engineer, plus any /debug record) | team | `docs/postmortems/-.md` | Acts. Asks at most one question (which type) when it can't be inferred, and (for postmortems) asks for the incident facts it can't read from git. ## Artifact ownership PR text, `CHANGELOG.md`, `docs/releases/`, `docs/postmortems/` (owned by this skill). It writes nothing else. --- ## Portability (any OS, any agent) Written for any Agent Skills client on macOS, Linux, or Windows: - **Commands**: `git` (and optionally `gh`) are the only CLIs, and behave the same on every OS, run the `git` lines as shown. Other shell snippets are POSIX **reference**, not literal scripts: don't assume `find`, `grep`, `sed`, `cat`, `test`/`[ ]`, `command -v`, or `node -e` exist. Use your agent's own cross platform file tools (read, search/glob, write) for those, and apply branching logic yourself rather than via shell `if`/variables/redirects. - **Bundled files**: referenced by paths relative to this skill's folder. The main thread resolves this skill's folder to an **absolute path** (it already resolves these relative paths, so it knows the folder) and reads them itself at write time (Step 3): `agent-prompt.md` and the one template for the chosen type. - **No interactive question support?** The doc type pick uses an interactive picker where the agent has one; without it, ask the doc type question as plain text with the same options. ## Execution ### 1. Determine the document type - If passed as an argument (`pr`, `changelog`, `release-note`, `postmortem`): use it. - Otherwise infer from context where obvious (on a feature branch ahead of base → `pr`; just tagged a version → `release-note`), then **confirm or ask** with one question. Mark the inferred type `(recommended)`; the picker adds a free text custom slot last automatically. Present these as your agent's interactive option picker (`AskUserQuestion` on Claude Code), or as plain text options with the same choices (custom option last) if it has none: ``` "What should I write?" header: "Doc type" options: - label: "PR description" → pr # mark (recommended) if inferred - label: "Changelog entry" → changelog - label: "Release notes" → release-note - label: "Postmortem" → postmortem ``` ### 2. Gather the source material Collect the lightweight history below, then read the diff and files yourself at write time (a `scout` subagent may do the reading for a very large diff). Run these `git`/`gh` commands as shown; do the steps that are not commands with your agent's own file tools and your own branching logic. ```bash # base branch: use `main` if it exists, otherwise `master` git rev-parse --verify main # current branch git rev-parse --abbrev-ref HEAD # pr / changelog: the branch change set (BASE = the base branch above) git log --oneline "BASE..HEAD" git diff --name-only "BASE...HEAD" # release-note: needs tags. List them; if there are none, fall back gracefully (treat as NO_TAGS). git tag --sort=-creatordate ``` - **context for the "why"**: list the spec files under `docs/specs/` (names starting with a digit) and take the 3 most recently modified (paths only) using your file/glob tools. - **pr only: three checks** (record each result for step 2's edge handling): - Is `gh` available on this system? (GH_INSTALLED) - Does the repo have a git remote? Run `git remote`; a result that is not empty means HAS_REMOTE. - Does a PR already exist? Run `gh pr view --json number -q .number`. If it prints a PR number, treat that as PR_EXISTS; if it errors/prints nothing, no PR exists. **Per type edge handling the main thread resolves before writing:** - **`release-note` range**: if tags exist, the range is `..` (or a range the engineer named). **If `NO_TAGS`**, don't guess, ask: "No version tags found. Give me a version name and range (e.g. `v1.0.0`, covering `..HEAD`), or I'll cover all commits since the first one." Pass the resolved range/version to the subagent. - **pr + gh**: only offer to create/update the PR via `gh` when **`GH_INSTALLED` and `HAS_REMOTE`**. If `PR_EXISTS`, the action is `gh pr edit` (update the body), **not** `gh pr create`. If gh isn't usable or no remote, the PR text is chat only, don't attempt `gh`. **Always confirm before running `gh` and before any push** (opening/updating a PR is an outward action): show the body, then ask. This holds regardless of the `AGENTS.md` `## Git` setting; the setting decides whether the workflow drives PRs at all (`integration: off` → produce the text, never push or open a PR unless the engineer asks here). - **postmortem**: git won't contain the incident narrative. Ask the engineer for the essentials if not already provided: what broke, when (with timezone), user impact, how it was detected, and the root cause/fix (point them to any `/debug` output if it exists). Pass their account as the incident facts. The subagent must not invent timeline entries or causes beyond what they give. ### 3. Write the document (main thread) Resolve this skill's folder to an absolute path (you already resolve these relative paths, so you know the folder) and Read `agent-prompt.md` and the **one** template for the chosen type, `templates/.md`, now (only now, at write time). Follow `agent-prompt.md` and write the document yourself. Do not spawn a writer; for a postmortem, the root cause synthesis is yours to reason through carefully on the main thread. The inputs to apply: 1. Document type + its template (the chosen one only; read it) 2. Source: commit list, diff command, and (postmortem) the incident facts. Read the diff yourself; for a very large diff (e.g. >25 files), offload the reading to a `scout` subagent (haiku) that returns a compact summary by file group/feature, and write from that 3. Project context contents (project name, conventions), read `AGENTS.md`, or `CLAUDE.md` fallback, + recent spec paths for the "why" 4. Output target for the type and today's date 5. **pr**: the gh action, `none (chat-only)` | `gh pr create` | `gh pr edit` (from the `GH_INSTALLED`/`HAS_REMOTE`/`PR_EXISTS` checks) 6. **changelog**: **match the existing `CHANGELOG.md` format** if the file exists (don't impose Keep a Changelog over a different established style) 7. **`release-note`**: the resolved version + range ### 4. Relay the result Lead with the type and where it landed; for `pr` the body IS the deliverable, so show it in full (per `docs/conventions.md`). Template: ``` ## /document · .md | docs/postmortems/ | PR #N updated> Scope: ticked `Document it` (or "no scope row matched"; omit if not on the scope) ``` This skill does not commit, push, or merge; it produces the prose (and ticks the `Document it` box per the closing gate above, the only scope edit it makes). --- ## Reference files - `agent-prompt.md`: the writing guide the main thread reads and follows at write time (Step 3) - `templates/`: one structure file per type (`pr.md`, `changelog.md`, `release-note.md`, `postmortem.md`); the main thread reads only the chosen one at write time

相关技能

文档办公

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,归档一个问题,更新一个电子表格,通过一个连接的搜索或刮取提供者运行一个查询. 每一次通话都到用户连接的应用…