nesnilnehc/assess-docs
skills/assess-docs/SKILL.md
Assess documentation core health in one pass — artifact norms compliance, layer readiness scoring, and minimum fill plan.
$ install --global
skillsauthnpx skillsauth add nesnilnehc/ai-cortex assess-docsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 29, 2026, 9:50 AM11.7s3 files scanned
SKILL.md
- name:
- assess-docs
- description:
- Documentation Assessment Report (compliance findings + layer readiness + minimum fill plan)
- description_zh:
- 一次性评估文档核心健康：规范合规、分层就绪度评分与最小补齐计划。
- tags:
- [documentation, workflow, governance]
- version:
- 4.1.0
- license:
- MIT
- recommended_scope:
- both
- author:
- ai-cortex
- triggers:
- [doc readiness, documentation readiness, doc gap, validate docs]
- type:
- document-artifact
- artifact_type:
- doc-assessment
- path_pattern:
- docs/calibration/doc-assessment.md
- lifecycle:
- living
技能：文档评估（Assess Docs）
目的 (Purpose)
在单次运行中评估文档核心治理状态：是否符合规范、证据是否足够支撑规划、缺口应如何最小化补齐。
核心目标（Core Objective）
首要目标：输出一份可执行的文档评估报告，明确合规问题、层级就绪度和最小补齐行动。
成功标准（必须全部满足）：
- ✅ 已解析项目规范（
docs/ARTIFACT_NORMS.md或默认契约） - ✅ 已完成路径/命名/front-matter 合规检查并给出 findings
- ✅ 已完成层级就绪度评分（strong/weak/missing）
- ✅ 已产出缺口优先级与最小补齐计划
- ✅ 已写入单一报告
docs/calibration/doc-assessment.md
验收测试：团队是否能仅凭报告明确“先修什么、后补什么、由谁处理”？
范围边界（Scope Boundaries）
本技能负责：
- 规范合规检查（路径、命名、front-matter）
- 文档层级证据盘点与就绪度评分
- 缺口排序与最小补齐计划
本技能不负责：
- 规范创建/更新（使用
define-docs-norms） - 代码-文档对齐分析（使用
assess-docs-code-alignment） - 链接图健康分析（使用
assess-docs-links） - SSOT 意图冲突审计（使用
assess-docs-ssot） - 仓库结构改造（使用
tidy-repo）
交接点：核心评估报告完成后，按问题类型交给对应拆分技能做专项评估。
使用场景（Use Cases）
- 里程碑前文档就绪检查
- 规划前快速判断证据完整性
- 文档债务清单和优先级梳理
行为（Behavior）
阶段 0：Norms Resolution + 范围解析（v4.1 更新）
按 specs/artifact-contract.md §8 Runtime Norms Resolution Protocol 实现本技能产出（doc-assessment）的 path_pattern 解析 + 同时解析被评估的项目规范作为评估基线：
- 解析 docs 根路径
- 按 §8.2 发现顺序读取项目规范（优先
.ai-cortex/artifact-norms.yaml，其次docs/ARTIFACT_NORMS.md）；不存在则回退specs/artifact-contract.md默认 - 读取项目规范中
doc-assessmentartifact_type 的path_pattern决定本次评估报告的输出路径（默认docs/calibration/doc-assessment.md）；本技能为固定路径治理产出 - 建立目标层映射（mission/vision/requirements/architecture/roadmap/backlog 等）用于后续阶段的评估
阶段 1：合规性验证
- 扫描 docs 内 Markdown
- 校验路径、命名、front-matter
- 形成 findings（location/category/severity/title/description/recommendation）
阶段 2：层级证据盘点
- 按层统计文档覆盖
- 判断证据新鲜度与可用性
- 标记每层状态（strong/weak/missing）
阶段 3：就绪度评分
- 计算层级评分与总体 readiness（high/medium/low）
- 标记关键阻断层
阶段 4：最小补齐计划
- 按影响与工作量排序缺口
- 形成最小行动集（先后顺序、责任建议、目标路径）
阶段 5：报告落盘
- 写入
docs/calibration/doc-assessment.md - 输出“核心问题 + 建议下一步技能路由”
输入与输出 (Input & Output)
输入
- docs 范围（默认仓库
docs/） - 可选层映射
- 可选目标就绪等级（
medium|high）
输出
docs/calibration/doc-assessment.md- findings + readiness + minimum fill plan
限制（Restrictions）
硬边界（Hard Boundaries）
- 不执行仓库结构写操作
- 不创建或更新
docs/ARTIFACT_NORMS.md - 不执行 code diff、links graph、SSOT 深度审计
技能边界 (Skill Boundaries)
不要做这些（其他技能负责）：
- 规范落盘：
define-docs-norms - 代码对齐：
assess-docs-code-alignment - 链接图：
assess-docs-links - SSOT 审计：
assess-docs-ssot
自检（Self-Check）
- [ ] 已解析规范来源（项目规范或默认契约）
- [ ] 已输出完整合规 findings
- [ ] 已完成层级 readiness 评分
- [ ] 已产出最小补齐计划
- [ ] 仅生成核心评估报告，无专项扩展报告
示例（Examples）
示例 1：标准核心评估
- 输入：现有 docs
- 输出：
doc-assessment.md（含合规+readiness+补齐计划）
示例 2：低就绪度项目
- 输入：仅有部分 roadmap/backlog 文档
- 输出：readiness=low，首要行动为补齐关键层文档
附录：输出合约 (Appendix: Output Contract)
本技能产出文档健康评估报告：
| 元素 | 格式 | 必填字段 | 路径模式 | | :--- | :--- | :--- | :--- | | 报告主体 | Markdown | front-matter（artifact_type=assessment / lifecycle=snapshot）；章节：规范合规 / 分层就绪度评分 / 最小补全计划 | docs/calibration/doc-assessment.md | | 规范合规 | 列表项 | rule_id / artifact_path / status（pass/fail/n-a）/ evidence | 「规范合规」节 | | 分层就绪度 | 表格 | layer / score（0-3）/ missing_artifacts / next_action | 「分层就绪度评分」节 | | 最小补全计划 | 列表项 | artifact_path / proposed_skill / priority / rationale | 「最小补全计划」节 |
Related Skills
nesnilnehc/scaffold-agent-tests
development
VerifiedTrustedCommunity
Generate an LLM agent test suite (golden cases, mock-LLM unit tests, evaluator harness) from an agent implementation and its agent-test contract. Use when an agent has no tests, or a contract exists but the test code is missing.
7SKILL.mdUpdated May 30, 2026
nesnilnehc/redeploy-local
development
VerifiedTrustedCommunity
After code changes, auto-detect the project's build system and local deployment method for a given directory, then build the project and restart its locally-deployed environment (Docker Compose / systemd / process manager). Never assumes — asks only when detection is ambiguous. Caches detected commands per project in .cortex/redeploy-local.yaml; re-invocations on the same project skip re-scanning until signal files change, the cache expires (30 days), or the skill version bumps.
7SKILL.mdUpdated May 22, 2026
nesnilnehc/publish-nats-message
tools
VerifiedTrustedCommunity
Publish a NATS message conforming to a cross-team contract, using NATS MCP tools. Authors the contract on first use if missing. Reads project-level cache (.cortex/nats.yaml) to avoid re-prompting basics across sessions.
7SKILL.mdUpdated May 22, 2026
nesnilnehc/consume-nats-message
tools
VerifiedTrustedCommunity
Drain pending NATS messages from a producer contract via NATS MCP tools (default batch / drain-style). Applies Tolerant Reader semantics and per-message ack/nak/term, returning aggregated stats. Reads project-level cache (.cortex/nats.yaml) to avoid re-prompting.
7SKILL.mdUpdated May 22, 2026