做什么
审计现有开发者文件集的结构——按Diátaxis模式分类的逐页清单(专题、方式、参考、解释)、混合模式和错误的页面、每个产品表面的覆盖差距、对文件树的导航漂移、CNCF TechDocs分数和优先补救队列
技能库 智客分类:文档办公 developer-docs-structure-audit
审计现有开发者文件集的结构——按Diátaxis模式分类的逐页清单(专题、方式、参考、解释)、混合模式和错误的页、每个产品表面的覆盖差距、导航漂移与文件树相向、CNCF TechDocs分数和优先补救队列。 每当用户提到docs结构或内容审计,docs信息架构,Diátaxis,"我们的文档是一团糟",docs漏洞分析,docs缺失的是什么,一个网页应该住在哪里,或者重新组织一个文档站点——即使他们只说"我们的docs很难导航". 不是写页 不使用 Docs 搜索排名 - 使用 samber/ developer- relations- swills@ docs-seo.
官方网址:skills.sh
先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。
审计现有开发者文件集的结构——按Diátaxis模式分类的逐页清单(专题、方式、参考、解释)、混合模式和错误的页面、每个产品表面的覆盖差距、对文件树的导航漂移、CNCF TechDocs分数和优先补救队列
任何用户都提到docs结构或内容审计,docs信息架构,Diátaxis,"我们的文档是一团糟",docs漏洞分析,docs缺失的是什么,一个页面应该存在的地方,或者重新组织一个文档网站——即使他们只说"我们的文档很困难"
按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Docs Structure Audit、Who should run this、Interview、Step 1 - Fix the scope and the evidence you have、Step 2 - Build the inventory、Step 3 - Classify every page。 其中含规范建议的小节:分步指令。
文件分析:除 SKILL.md 外,正文引用了 references/validation-and-governance.md、references/docs-platform-nav-sources.md、scripts/docs-inventory.py、references/diataxis-classification.md、references/gap-and-signal-analysis.md、references/scoring-rubrics.md,属于带资源的技能包,这些文件按需再读。
Audits an existing developer documentation set's structure - a page-by-page inventory classified against the Diátaxis modes (tutorial, how-to, reference, explanation), mixed-mode and misplaced pages, coverage gaps per product surface, navigation drift against the file tree, a CNCF TechDocs rubric score, and a prioritized remediation queue. Use whenever the user mentions a docs structure or content audit, docs information architecture, Diátaxis, "our documentation is a mess", a docs gap analysis, what docs are missing, where a page should live, or reorganizing a documentation site - even if they only say "our docs are hard to navigate". Not for writing pages. Do NOT use for docs search ranking - use samber/developer-relations-skills@docs-seo.
Docs Structure AuditWho should run thisInterviewStep 1 - Fix the scope and the evidence you haveStep 2 - Build the inventoryStep 3 - Classify every pageStep 4 - Find what is missingStep 5 - Check that navigation tells the truthStep 6 - ScoreStep 7 - Validate before recommending a restructureStep 8 - Turn findings into a queueStep 9 - Deliver, then close the drift loop
· 许可:MIT
来源分类:skills.sh agent-skill
namedeveloper-docs-structure-auditdescriptionreferences/validation-and-governance.mdreferences/docs-platform-nav-sources.mdscripts/docs-inventory.pyreferences/diataxis-classification.mdreferences/gap-and-signal-analysis.mdreferences/scoring-rubrics.md以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。
具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗
先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。
该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。
复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。
把 Agent Skill「developer-docs-structure-audit」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-32f82011283c7985-%E5%BC%80%E5%8F%91%E8%80%85-Docs-%E7%BB%93%E6%9E%84%E5%AE%A1%E8%AE%A1.html 请存为 .cursor/skills/developer-docs-structure-audit/SKILL.md 或 .claude/skills/developer-docs-structure-audit/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。 该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/samber/developer-relations-skills 取完整目录,不要只建一个 SKILL.md。
需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。
npx skills add 'https://github.com/samber/developer-relations-skills' --list
npx skills add 'https://github.com/samber/developer-relations-skills' --skill 'developer-docs-structure-audit'
CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。
You are an information architect for developer documentation. Someone has a docs set that already exists and a suspicion that readers cannot find what they need.
Say, with evidence, page by page:
Hand back a queue of small moves the team can actually ship.
In scope: placement, coverage, findability.
Out of scope: writing the pages, verifying that documented behaviour matches the code, editing prose. When the request is really "write this page", route it to the sibling skills listed under References instead of absorbing the work.
This work belongs to an information architect or content strategist. The field's own data shows what happens when a generalist runs it instead: the State of Developer Relations Report 2023 found 44% of respondents "Never" audit their developer experience or review developer journey maps, and only 1% review monthly - down from 12.4% the year before.
Two things follow:
Ask one question at a time, multiple-choice where you can, and skip anything already answered. Questions 1-4 gate the audit; do not classify a single page before they are answered.
ms.topic, Good Docs templates, house-defined, or none?Questions 10, 12, 13 and 14 re-rank the queue in Step 8, so ask them before you classify:
If the user cannot answer 3, infer the audience from the top entry pages in analytics and say in the report that the audience is inferred - mode balance judged against the wrong audience produces confident, wrong recommendations.
Decide what you can see before promising what you can measure:
Drop from the scorecard any measure your evidence cannot support, and say so in the report. See ./references/docs-platform-nav-sources.md for where navigation lives per generator and the crawl fallback.
Keep the two halves of the pass distinct:
Build the inventory first, completely, before judging anything.
Run the inventory script over the docs tree; it collects the per-page facts that classification runs on, plus orphan candidates when you pass the navigation config.
python3 scripts/docs-inventory.py ./docs --nav mkdocs.yml > inventory.tsv
Per-generator flags (--nav, --ext, --min-words, --format json), the emitted columns and how to read them are in the platform reference.
Add the columns the script cannot know - owner, page views, top search-entry queries, top 404s - from whatever analytics the user has, and flag each page Redundant, Outdated or Trivial. ROT is the standard content-audit heuristic and it does most of the triage work for free: an outdated page in a well-placed section still fails its reader.
If you cannot execute scripts or read the tree directly, build the same inventory by hand from the navigation and the pages you can open, and note in the report that it is partial.
Do not classify from the numbers alone. Use them to triage - these cutoffs are this skill's working defaults, not published figures. Open:
On a large docs set, cover the top 20 pages by traffic in full before sampling.
Apply the compass to each page's dominant content: does it inform action or cognition, and does it serve the reader's acquisition of skill (study) or application of skill (work)? Those two answers give the mode.
If the site already declares a different taxonomy (question 7), audit against that one instead and say so up front. Practitioners converge on consistency mattering more than which framework supplies it, so a DITA site applying concept/task/reference cleanly is healthy, and telling it to convert is expensive advice. Recommend a switch only when the declared taxonomy is applied inconsistently or leaves a whole reader need uncovered.
Record for each page:
Two disagreement types follow:
Read ./references/diataxis-classification.md for acceptance criteria per mode, the mixing symptom table, worked examples, the hard cases (release notes, FAQ, troubleshooting, generated API docs), and how to audit a DITA, EPPO, Microsoft, or Good Docs site.
Flag mixing only when the second mode occupies roughly a fifth of the page - this skill's working line, not a published threshold - or contains something the reader must act on. Flagging every stray sentence produces a report nobody triages.
Build the coverage matrix: product surfaces as rows, the four modes as columns, existing pages in the cells. Empty cells are candidate gaps, not confirmed ones.
Confirm each candidate against a demand signal from the signal table in ./references/gap-and-signal-analysis.md, which also has the matrix and the audience weighting (self-serve versus enterprise evaluation). A gap with evidence goes in the queue with the evidence attached; a gap without evidence gets listed as a question for the team, not as work.
Run the mechanical checks first - the inventory script, the nav config and a link checker answer these without judgement:
Confirm orphans against front matter before reporting; draft, hidden and unlisted pages are intentional.
Then open pages and judge these by hand:
Score twice: the rubric rating travels outside the docs team; the scorecard drives the remediation queue.
Rate each top-level section on the CNCF TechDocs rubric's project-documentation criteria, on its published 1-to-5 scale - the most concrete public instrument for scoring a docs set, and a rating a third party would recognise. Then compute the structural scorecard from the inventory; the eleven measures, how to compute each, and each threshold's source are in ./references/scoring-rubrics.md, along with the rubric's published calibration ratings and the maturity read that explains a docs set that keeps drifting back.
Label every threshold with where it came from. The CNCF scale is published; the scorecard's pass marks are this skill's own baseline, so agree them with the user before scoring rather than importing them silently. Treat the audit as unfinished while any must-fix measure fails - after each remediation batch, re-run the inventory, re-score, and report the delta.
Classification says what is wrong today; only user testing says whether your proposed structure is better. When question 9 says testing is possible, card sort to design the categories and tree test to validate them, then read the result before writing the queue.
One reading changes the plan outright: above roughly 80% task success and 60% direct-path rate across core tasks, cancel the restructure and spend the budget on gap-filling and freshness instead. These are practitioner heuristics from one guide plus one case study, not a standard, so treat a borderline number as a prompt to talk to the team, not a verdict.
When testing is not possible, downgrade every structural recommendation from "validated" to "proposed" in the report, and lean harder on top 404s, zero-result searches and high-exit landing pages as substitutes.
./references/validation-and-governance.md has the method, real sample sizes, the full interpretation table and its sourcing.
Order the work so every item ships alone and improves the docs by itself. Diátaxis's own remediation loop is deliberately small:
It rules out two moves you should rule out too:
Within that loop, order the queue by reader need fixed per hour of writing and review - not by how many findings an action closes, and not by what is cheapest. The Diátaxis loop prescribes only one small action at a time; the ranking below is this skill's own.
| Action | Effort | Reader need it fixes | | -------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------- | | Split a mixed page | a day - both halves rewritten, two URLs, one redirect; no SME arbitration | the reader stops landing on a page doing two jobs | | Merge duplicates | a day or more - someone with authority must say which text is true | the reader stops getting two contradictory answers | | Move a page | an hour - a path change plus its redirect | the reader finds the page where the section promised it | | Write a missing page | a week, then a refresh every release - permanent surface | the reader gets an answer where they got nothing | | Rename a section | an hour of editing, but every child URL and deep link moves with it | the reader reads a label matching what is inside |
Split leads on efficiency despite merging being worth more, because a merge blocks on someone else deciding which text is correct and a split does not. Default to shipping every split first, and move up to merging as soon as a duplicate pair is giving contradictory answers on the adoption path.
This order starves the missing page: highest value on a gap with a confirmed demand signal, a week of writing plus upkeep every release, so it loses every round and the section ratings never move while only cheap edits ship. Promote it anyway when the same question recurs in support week after week, or when the gap sits on the adoption path.
Delete rather than demote what the constraints rule out:
Say which you deleted, and spend the budget on splits and gaps.
The ranking is a default, not a law, and it shifts with who executes it. Re-rank against what you already know:
When a page must move and URLs are load-bearing, name the redirect as part of the action.
Produce the report in the shape given by ./references/audit-report-template.md - verdict, CNCF section ratings, scorecard, coverage matrix, findings by severity, remediation queue, drift controls, what the audit did not cover, and which inputs were available - using that file's finding format and severity tiers verbatim.
When the team will act on it, split the deliverable the way CNCF does - report, implementation plan, tickets - using the wording in the scoring reference. Present it section by section and get the user's agreement on each before moving on; a queue built on a wrong surface list wastes a whole sprint of writing time.
Close with the drift controls from the validation-and-governance reference, because a structure fixed once and left ungoverned decays:
If your environment has persistent memory, store the audit's durable decisions:
A re-score six months later is worthless if the definitions moved in between.
| Failure | What it looks like | Fix | | --------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- | | Framework worship | Findings phrased as "violates Diátaxis" | Phrase every finding as a reader failing to get something | | Cheapest-first queue | Renames and moves at the top because they take an hour | Order by reader need fixed per hour, and say so in the report | | Classification bikeshedding | Ten minutes on whether a page is reference or explanation | Apply the "while working / away from work" test, mark low confidence, move on | | Over-flagging | 200 findings on a 200-page site | Report only the pages where a reader's need actually fails | | Scope creep into accuracy | Findings about wrong code samples | Note them separately as out of scope with an owner | | Audience blindness | Enterprise evaluator content judged as tutorial bloat | Settle the audience in the Interview, weight the target mix accordingly | | Silent inference | Classification from titles presented as fact | Label evidence strength per finding | | Audit with no governance | Report delivered, no CI check, same mess in a year | Ship the drift controls with the queue, not after it |
文档办公
为结构化的代理内存和可堆肥技能所打入的知识图. 在创建/征服实体(Person, project, Task, Evention, Document)时使用,链接相关对象,强制约束,规划多步动作作为图变,或技能需要共享状态时使用. 触发到"记住","我知道什么","链接X到Y",…
文档办公
使用纳米-pdf CLI编辑带有自然语言指令的PDF.
文档办公
创建,检查,并编辑有可靠样式的Microsoft Word文档和DOCX文件,编号,跟踪更改,表格,章节,并进行相容性检查. 当 (1) 任务涉及 Word 或 ".docx " 时使用; (2) 文件包括跟踪的更改,评论,字段,表格,模板,或页面布局限制; (3) 文档必须在不…
文档办公
通过 Maton 网关调用第三方 API, 它为用户已经连接的应用程序注入证书 。 当用户命名一个连接的应用程序和其中的具体行动时使用此技能——读取一个邮箱,查询一个CMM,归档一个问题,更新一个电子表格,通过一个连接的搜索或刮取提供者运行一个查询. 每一次通话都到用户连接的应用…