返回技能目录
人工审校软件开发

技能研究档案

code-documenter

来源声明

Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides. Use when adding docstrings to functions or classes, creating API documentation, building documentation sites, or writing tutorials and user guides. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, getting started guides.

保留作者的英文原始描述。它表达设计意图,不代表已验证的实际效果。

Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides. Use when adding docstrings to functions or classes, creating API documentation, building documentation sites, or writing tutorials and user guides. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, getting started guides.

developmentreferences

研究摘要

人工审校

Skill Atlas editorial review · editorial-preview-1.0.0

添加并验证技术文档,包括 docstring、JSDoc、OpenAPI 规范与使用指南,先询问格式偏好,并在汇报前测试示例。

审阅范围

对所收集的 SKILL.md 及辅助文本/代码进行确定性静态分析。机器辅助候选和发现等待人工编辑复核;不评估动态行为或效果。

可观察能力

  • 先询问格式偏好与排除项,再识别语言与框架。
  • 找出未文档化的代码,并统一应用文档风格。
  • 用 doctest、tsc --noEmit 或 Redocly lint 验证示例,失败则先修复再汇报。
  • 生成文档覆盖率摘要。

限制与范围

  • pytest、tsc、Redocly 等验证工具需已安装且适用于项目。
  • doctest 或编译检查通过并不能证明文字描述准确。
  • 文档站点与教程的指导在独立参考文件中,主文件未展开。

适用读者

  • 为公共 API 编写文档的开发者
  • 需要提升 OpenAPI 或 JSDoc 覆盖率的团队
  • 编写入门指南的维护者

技能包含哪些内容

文件清单来自记录提交中的采集源码。路径与大小属于结构观察,不代表质量评价。

个文件
9
Markdown 文件
9
个脚本
0
个引用
8
大小
50.1 KB
结构复杂度
中

文件清单

路径类型字节
skills/code-documenter/references/api-docs-fastapi-django.md引用4.1 KB
skills/code-documenter/references/api-docs-nestjs-express.md引用4.8 KB
skills/code-documenter/references/coverage-reports.md引用3 KB
skills/code-documenter/references/documentation-systems.md引用6 KB
skills/code-documenter/references/interactive-api-docs.md引用10 KB
skills/code-documenter/references/python-docstrings.md引用2.9 KB
skills/code-documenter/references/typescript-jsdoc.md引用3 KB
skills/code-documenter/references/user-guides-tutorials.md引用10.7 KB

SKILL.md 前置元数据

{
  "name": "code-documenter",
  "description": "Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides. Use when adding docstrings to functions or classes, creating API documentation, building documentation sites, or writing tutorials and user guides. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, getting started guides.",
  "license": "MIT",
  "metadata": {
    "author": "https://github.com/Jeffallan",
    "company": "https://synergetic.solutions",
    "version": "1.1.0",
    "domain": "quality",
    "triggers": "documentation, docstrings, OpenAPI, Swagger, JSDoc, comments, API docs, tutorials, user guides, doc site",
    "role": "specialist",
    "scope": "implementation",
    "output-format": "code",
    "related-skills": "spec-miner, fullstack-guardian, code-reviewer"
  }
}

对运行顺序的一种解读

此工作流根据源码材料重建表面顺序。除非明确记录受控评估,否则它属于暂定解读,而非真实运行轨迹。

  1. 01
  2. 02
    操作

    分析未文档化代码

    识别语言与框架后,找出未文档化的代码。

  3. 03
    判断

    修复验证失败

    若验证失败,先修复示例并重新验证,再进入汇报步骤。

  4. 04
    输出

    交付文档

    视任务交付已补全文档的文件与覆盖率报告、规范、文档站配置或指南。

潜在风险面

静态发现用于提示安装前需要检查的位置,不能证明一项技能安全、恶意或有效。

建议重点关注

收集的文本中有 93 项确定性词法发现需要复核。发现可能仅位于文档中,不证明已执行或可被利用;仅含二进制的文件未扫描。

网络访问已观察到
文件写入已观察到
凭据使用已观察到
提示

文本描述或实现了文件修改

59 次命中

此行包含可能的文件写入或重定向操作。应检查目标路径和覆盖行为;静态审查没有写入任何文件。 该规则在收集文本中命中 59 处;此处列出 3 个代表位置。命中文本可能只是文档,分析器没有执行它。

中

文本提及网络访问

22 次命中

此源文件行包含 URL 或网络客户端。应检查目标地址、发送的数据和信任边界;静态文本无法证明实际发生了网络活动。 该规则在收集文本中命中 22 处;此处列出 3 个代表位置。命中文本可能只是文档,分析器没有执行它。

高

文本引用凭据或密钥材料

12 次命中

此行疑似凭据字面值,或读取敏感环境变量。请勿暴露其内容;应核实它是占位符、所需密钥,还是误提交的敏感材料。 该规则在收集文本中命中 12 处;此处列出 3 个代表位置。命中文本可能只是文档,分析器没有执行它。

编辑安全提示

检查文档示例与生成的规范中是否泄露真实密钥、内部网址或私有端点信息。

上下文可能消耗在哪里

发现、激活与资源层具有不同含义。只有使用指定官方方法并记录模型的运行时,才显示精确数值。

精确 token 计数不可用

在管线使用明确模型执行官方精确计数之前,包括文件清单在内的所有 token 值均为 null。

未使用要求的官方方法记录 token 测量。本档案不会用字符数、文件大小或估计值替代。

受控评估

没有受控评估

该技能仅具备以上标明的证据。不声称任何任务成功率、token 效率、延迟或质量优势。

尚未测试

在源码可见的情况下使用

安装命令
git clone https://github.com/Jeffallan/claude-skills.git cd claude-skills # 将该 Skill 目录复制到以下任一位置: # ~/.claude/skills/code-documenter # .claude/skills/code-documenter
  1. 打开固定版本源码:https://github.com/Jeffallan/claude-skills/blob/67c1961b180dc92cf08983344627109e983e8f51/skills/code-documenter/SKILL.md。
  2. 审阅许可证、前置条件和所有捆绑的参考文件。
  3. 将 Skill 安装到个人或项目级 Claude Code skills 目录。
  4. 重启或刷新 Claude Code,使该 Skill 可被发现。
验证安装

确认目标位置存在 code-documenter/SKILL.md,然后让 Claude Code 在一个小型测试任务中使用 code-documenter Skill。

前置条件

  • pytest、tsc、Redocly 等验证工具需已安装且适用于项目。
  • doctest 或编译检查通过并不能证明文字描述准确。
  • 文档站点与教程的指导在独立参考文件中,主文件未展开。

示例提示词

代表性任务

Use the code-documenter skill to add Google-style docstrings to the public functions in src/users.py, ask me about format first, and validate the examples with doctest.

使用前检查

Read the code-documenter skill at https://github.com/Jeffallan/claude-skills/blob/67c1961b180dc92cf08983344627109e983e8f51/skills/code-documenter/SKILL.md and its referenced files. Explain its workflow, required tools, permissions and the main risks before I decide whether to install it.

附上限制条件的判断

优势

  • 要求先询问 docstring 格式,而不是自行假定。
  • 把文档与示例的可执行验证绑定在一起。

注意事项

  • 为所有公共函数补文档可能带来很大的改动量。
  • 覆盖率报告只衡量文档是否存在,而非质量。
研究结论

可靠的文档工作流,在示例可被编译或校验的场景中效果最好。

从结构上保持可追溯

档案是对公开工件的限时阅读,而非背书。请通过来源链接检查确切的上游材料。

Jeffallanclaude-skillsskills/code-documenter
来源类型
社区
提交
67c1961b180dc92cf08983344627109e983e8f51
采集时间
2026年11月20日
最近核查
2026年11月20日
上游许可证
MIT
仓库星标
12,464
内容依据

仅对提供的文件进行确定性词法解析、YAML frontmatter 校验、文件清单、来源描述的工作流程提取和启发式暂定分类。由机器生成;无 LLM、执行、动态测试或人工编辑批准。