/skill-lint

name: skill-lint
homepage: https://github.com/cat-xierluo/legal-skills
author: 杨卫薪律师（微信ywxlaw）
version: "2.9.3"
license: MIT
description: Skill 创建预检、可靠性验收与格式审查工具。本技能应在用户创建、重大改造或审查Skill，需要识别旧版 Skill 的指令遵循不稳定、产出漂移、验证模态错配、约束漏检，或检查 Harness 契约、候选绑定证据、故障注入、目录结构、业务流和安全风险时使用。不要用于：代替业务领域验证器、代码审查、应用功能测试、通用编程任务。

Skill Lint

本技能负责 Skill 创建前设计预检和创建后质量验收：审查一个 Skill 是否结构合规、文档一致、可发布、可评估、安全风险可控，判断它是否真实承载业务流程，并检查“完成”结论是否由候选绑定证据和多轮真实产物支撑。

本技能不代替主要创建者或领域验证器。创建或大改 Skill 时，用它先审查 Harness 设计，再由创建工具实现，完成后回到本技能做候选绑定验收。

工作原则

• 先看硬性问题，再看优化问题。
• 先做静态审查，再判断业务流深度。
• 先定位审查单元，再审查目标 Skill 目录及明确给出的上下文。
• 不把格式合规等同于任务效果通过。
• 不采信生产者自报的 PASS；正式验收必须绑定当前候选、当前规则和实际日志。
• 不把“有 checker”当作“覆盖完整”；每条硬约束必须追踪到合适模态、正确产物阶段和回归用例。
• 不比较自然语言输出的整文件哈希；只比较合同声明的关键覆盖集合和可观察不变量。
• 客观缺陷 fail-closed；语义质量保留人工判断，不伪装成万能自动化。
• 只审查领域 checker 的覆盖、模态和证据，不把证据不足冒充为已经发现具体领域算法错误。
• 已知漏报必须有最小违规反例，已知误报必须有合法近似正例；两者都由目标 Skill 的领域 checker 定义。
• 对无法确认的能力标注“未提及/待补充”。

输入

审查时至少需要：

• 目标路径或仓库地址：可以是单个 Skill 目录、monorepo 根目录、GitHub 仓库或待改造的提示词集合
• 审查目的：创建前设计预检、发布前验收、改造评估、他人 Skill 审查、回归检查等

可选输入：

• 用户给出的特殊偏好或项目规则
• 本地审查配置文件，如 `config/review-profile.local.yaml`
• 需要重点关注的问题清单

如需配置个人或项目的发布元数据策略，先复制 `config/review-profile.example.yaml` 为 `config/review-profile.local.yaml`，再填入本地值。个人偏好只作为本地上下文使用，不写入公开文件，不复制到审查报告中，除非用户明确要求公开。

审查流程

0. 选择模式

• **创建预检**：目标尚未实现或将重大改造。先读取 `references/harness-reliability-standards.md`，产出七层 Harness 设计、Hard Fail 和至少一个逃逸反例；不要直接扩大提示词。
• **快速审查**：检查第三方 Skill、草稿或局部问题。可以只做静态与语义审查，但结论必须写 `NOT_VERIFIED`，不得称功能已验收。
• **旧版稳定性审查**：检查老版本、多维 review、视觉生产或反复漏项的 Skill。先读取 `references/instruction-stability-standards.md` 并运行静态 `assess`；缺少约束追踪合同或多轮证据时标记 `NOT_VERIFIED`，不得用一次成功执行推断稳定。
• **正式验收**：发布、交付或声称“稳定完成”前，除全部审查模块外，还必须运行候选绑定证据门禁。动态执行只用于用户已确认的自有/可信候选；未知第三方候选默认停在 `NOT_VERIFIED`，除非用户明确授权并使用隔离环境。

创建预检完成后，由用户指定的创建工具或实现者落地；本技能在实现完成后重新进入正式验收。这样既把可靠性理念前移，又不让审查器与生产器混成同一责任。

1. 确认范围

先读取 `references/repository-skill-discovery-standards.md`，判断输入目标是哪一类：

• 单个 Skill 目录：目标目录自身包含 `SKILL.md`
• monorepo / Skill 集合：仓库根目录只是容器，内部多个子目录才是最小 Skill 单元
• 松散提示词集合：没有标准 `SKILL.md` 单元，但存在带 `name` / `description` frontmatter 的 Markdown 或 README 索引
• 普通仓库：没有足够证据表明包含 Skill

不要只因为仓库根目录缺少 `SKILL.md` 就判定整个仓库不合格。根目录缺少 `SKILL.md` 只有在用户明确指定根目录就是单个 Skill，或仓库声明自己是一个可加载 Skill 根目录时，才按严重问题处理。

发现候选单元后，先列出：

• 已确认 Skill 单元：目录内有 `SKILL.md`
• 非标准但可迁移的 Skill-like 文档：单个 Markdown 带 `name` / `description` frontmatter，或 README 明确称为 skill
• 仓库级治理文件：README、LICENSE、CHANGELOG、Marketplace、贡献说明

如果候选单元很多，先按用户指定范围审查；用户未指定时，优先审查已确认 Skill 单元，并抽样检查 Skill-like 文档，报告中说明抽样范围。

2. 扫描文件

对每个已确认或被选中的候选单元列出文件，并重点检查：

• `SKILL.md`
• `CHANGELOG.md`
• `LICENSE.txt`
• `config/*.example.*`
• `references/*.md`
• `scripts/*`
• `assets/*`
• `templates/*`
• `archive/.gitkeep`

如果在 Skill 单元内出现 `.env`、真实密钥、`__pycache__/`、`docs/`、`test/` 等发布版不应包含的内容，按严重程度记录。仓库根目录的 README、docs、LICENSE、CHANGELOG 可以是 monorepo 治理文件，不按单个 Skill 目录结构误判。

3. 模块化规则审查

先读取 `references/skill-standards.md` 作为审查索引，再按问题类型读取对应模块。不要一次性把所有细则混在一份报告逻辑中。

默认模块：

• `repository-skill-discovery-standards.md`：仓库类型、monorepo、最小 Skill 单元和候选文档发现
• `structure-standards.md`：目录结构、文件可达性、references 命名
• `frontmatter-metadata-policy.md`：通用字段与发布字段分层
• `trigger-description-standards.md`：`name` 与 `description` 触发边界
• `configuration-privacy-standards.md`：配置模板、本地配置隔离、公开内容去具体化
• `security-assessment-standards.md`：危险执行、敏感访问、数据外传、凭证、依赖、MCP 和提示词安全
• `publishing-standards.md`：LICENSE、CHANGELOG、version、README / marketplace 同步
• `workflow-output-standards.md`：SKILL.md 正文、依赖、脚本、输出和可编排性
• `business-flow-rubric.md`：业务流深度、Hard Fail 和可评估性基础
• `harness-reliability-standards.md`：七层 Harness、独立验证、候选绑定证据、故障注入和闭环
• `instruction-stability-standards.md`：约束追踪、验证模态、产物阶段、多轮覆盖和漂移判定
• `reporting-standards.md`：问题分级和报告结构

`LICENSE.txt`、`version`、README 和 Marketplace 属于发布治理，不属于普通目录结构硬要求。审查私人或第三方普通 Skill 时，只有在用户给出发布目标或项目规则时才按发布模块判定。

4. 安全性评估

读取 `references/security-assessment-standards.md`，对纳入审查的 Skill 单元做安全风险评估。

**先运行确定性静态安全扫描**（对应 NVIDIA SkillSpector 的漏洞模式）：

# 单个 Skill
python3 scripts/security_scan.py audit --candidate-root /path/to/skill

# Skill 集合 / monorepo（递归发现所有含 SKILL.md 的最小单元）
python3 scripts/security_scan.py batch --root /path/to/skills

# 联网查询 OSV 已知漏洞（默认离线只做版本 pin 检查）
python3 scripts/security_scan.py audit --candidate-root /path/to/skill --online

扫描器输出含文件、行号、能力信号、严重级、置信度与修正建议的结构化 JSON；存在 critical/high finding 时退出码 1（FAIL），未发现 SKILL.md 时退出码 2。覆盖：危险执行（subprocess/os.system/eval/exec/动态导入）、网络外传、环境变量/敏感文件访问、运行时自动安装、未固定依赖与已知 CVE、硬编码凭证、提示注入、污点流（env/argv/input → subprocess）、文件系统枚举、隐藏 Unicode 字符、MCP 通配权限，以及"能力存在但文档未披露/未声明权限"（Missing User Warnings / MCP Least Privilege / Context-Inappropriate Capability）与文档级 scope creep（commit 技能引导发布/改 allowlist 等未披露的高风险动作）。

重点检查：

• `SKILL.md` 和 references 是否含提示注入、绕过安全限制、隐藏执行、敏感数据收集或欺骗性描述
• scripts 是否含危险命令执行、下载并执行、权限提升、无边界删除、敏感文件访问、数据外传、动态导入或混淆
• config/example 是否含真实凭证、真实 endpoint、真实 webhook 或本地敏感路径
• 依赖、安装钩子、MCP、网络请求和外部工具权限是否有用途说明、范围限制和用户确认
• GitHub 仓库审查时，提交历史是否出现过敏感信息泄露、异常删除重加或与 Skill 行为不一致的提交

安全评估不等同于完整渗透测试。对扫描器命中项要结合上下文判断误报；但涉及凭证泄露、下载并执行、权限提升、持久化、无确认数据外传、隐藏提示词指令等问题时，默认按严重问题处理。

5. 业务流深度审查

使用 `references/business-flow-rubric.md` 检查：

• Trigger：是否清楚说明何时触发、何时不触发
• Intake：是否识别输入缺口并规定追问方式
• Reasoning：是否区分事实、归纳、判断和依据
• Output：是否定义输出结构、验收标准和后续动作
• Safety：是否控制隐私、过度承诺和高风险场景

默认采用中等严格度：Hard Fail 是硬指标，五层评估对象是软指标。

6. Harness 可靠性审查

创建预检、重大改造和正式验收必须读取 `references/harness-reliability-standards.md`，逐层检查 Contract / Producer / Verifier / Evidence Binding / Fault Injection / Closure / Composition。旧版、多维审阅、视觉生产或用户反馈“反复漏项/产出漂移”时还必须读取 `references/instruction-stability-standards.md`。

先运行不执行候选代码的具体失效审查。单 Skill：

python3 scripts/harness_failure_audit.py audit \
  --candidate-root /path/to/skill

Skill 集合或 monorepo：

python3 scripts/harness_failure_audit.py batch \
  --root /path/to/skills

该审查器递归发现包含 `SKILL.md` 的最小单元，输出带文件、行号、证据、影响和修正建议的稳定 JSON；hard finding 返回 1，范围错误或集合中零 Skill 返回 2。规则 ID 与边界见 `references/harness-reliability-standards.md`。默认只做静态审查，不执行、安装或联网。

旧版结构性稳定性审查：

python3 scripts/instruction_stabilit