fluxly Search skills… ⌘K 中文 Sign in Publish

skill-lint

Documentation Community v1.4.0

Repo stars 248
License MIT License - 详见 LICENSE.txt
Author repo legal-skills

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: 对指定的 skill 进行格式合规性审查，生成结构化的审计报告。使用 Glob 工具列出技能目录下的所有文件：检查项： [ ] SKILL.md 是否存在 [ ] 是否有不规范的目录（如 test/、docs/ 应改为 references/） [ ]…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “审查流程”, “1. 扫描目标技能”, “2. 检查目录结构”, “3. 检查 Frontmatter”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name skill-lint directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “审查流程 / 1. 扫描目标技能 / 2. 检查目录结构” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / env-read; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Skill 格式审查工具

对指定的 skill 进行格式合规性审查，生成结构化的审计报告。

审查流程

1. 扫描目标技能

使用 Glob 工具列出技能目录下的所有文件：

<skill-path>/
├── **/*.md
├── **/*.py
├── **/*.yaml
├── **/*.json
└── ...

2. 检查目录结构

验证是否符合标准目录结构：

skill-name/
├── SKILL.md          # 必需
├── LICENSE.txt       # 可选
├── CHANGELOG.md      # 可选（推荐）
├── TASKS.md          # 可选（开发上下文，保留）
├── DECISIONS.md      # 可选（开发上下文，保留）
├── references/       # 可选
├── scripts/          # 可选
├── templates/        # 可选
└── assets/           # 可选

检查项：

SKILL.md 是否存在
是否有不规范的目录（如 test/、docs/ 应改为 references/）
是否有不应提交的文件（如 __pycache__/、.env、.DS_Store）

豁免文件（以下文件为开发过程上下文，不应标记为不合规，不应建议删除）：

TASKS.md — 任务追踪
DECISIONS.md — 决策记录
CHANGELOG.md — 变更日志

3. 检查 Frontmatter

解析 SKILL.md 的 YAML frontmatter：

---
name: skill-name
description: 功能描述。本技能应在...时使用
version: "1.0.0"
license: MIT
author: 杨卫薪律师（微信ywxlaw）
homepage: https://github.com/cat-xierluo/legal-skills
---

检查项：

name 字段是否存在且格式正确
description 字段是否存在
description 是否使用第三人称（"本技能应在...时使用"）
description 是否包含触发场景描述
description 是否包含负向触发条件（"不要用于..."）
description 长度是否 ≤ 1024 字符
是否有 license 字段
如有 version 字段，是否与 CHANGELOG.md 最新版本一致
如有 README 或 marketplace 索引，版本是否同步

4. 检查 SKILL.md 行数

检查项：

SKILL.md 行数是否 ≤ 500 行（超出应拆分到 references/）

5. 检查目录层级

检查项：

references/ 是否完全扁平（文件直接放在目录下，无子目录）
scripts/ 是否完全扁平（文件直接放在目录下，无子目录）
assets/ 是否完全扁平（文件直接放在目录下，无子目录）
templates/ 是否完全扁平（文件直接放在目录下，无子目录）

注意：所有二级目录（references/、scripts/、assets/、templates/）下禁止创建子目录，文件必须直接放在目录根。

6. 检查文档一致性

扫描所有 .md 文件，提取引用的文件路径：

提取模式：

scripts/xxx.py
assets/xxx.yaml
references/xxx.md
相对路径引用

检查项：

引用的脚本文件是否存在
引用的配置文件是否存在
引用的参考文档是否存在
README.md 是否与 SKILL.md 内容重复

7. 检查冗余内容

检查项：

是否有根目录 README.md（应删除，与 SKILL.md 重复）
references/ 中的文档是否都引用了实际存在的文件
是否有过时的文档（描述已废弃的功能）
SKILL.md 中是否有大段代码（>20行应移至 scripts/）

8. 检查配置文件

检查项：

配置模板是否使用 *.example.* 命名
实际配置文件是否被 .gitignore 忽略
config.example.yaml 的字段是否与实际代码匹配

9. 检查技能协作规范

检查项：

是否直接引用其他技能的内部脚本路径（应改为自然语言描述）
协作描述是否使用松耦合方式

10. 检查模块化设计

检查项：

独立功能是否解耦到单独脚本
是否存在跨 skill 直接调用内部脚本（应通过 AI 协调）

11. 检查安全审计

检查项：

无硬编码 API keys
无危险删除命令（rm -rf ~、rm -rf /、rm -rf $HOME）
删除命令是否使用安全方式（trash 或 find -delete）

12. 检查输出模式

检查项：

是否提供输出格式模板（对于需要一致性输出的技能）
模板严格度是否适中（严格需求用 ALWAYS，灵活需求用 use your best judgment）
是否提供输入/输出示例（对于质量关键的输出）
示例是否覆盖典型场景（至少 2-3 个）

13. 检查工作流模式

检查项：

复杂任务是否有流程概览（步骤编号清晰）
是否有条件分支逻辑（使用粗体问题 + 箭头指向）
每个分支是否有完整的执行步骤

14. 检查 CHANGELOG 规范

检查项：

是否存在 CHANGELOG.md 文件（推荐有）
格式是否符合规范（版本号 + 日期 + 变更内容）
版本号是否遵循语义化版本（v1.0.0 格式）
日期格式是否统一（YYYY-MM-DD）
变更类型是否清晰（新增/修改/修复/移除）

CHANGELOG 格式规范：

# Changelog

All notable changes to this skill will be documented in this file.

## [v1.1.0] - 2026-02-24

### 新增
- 添加了 XXX 功能

### 修改
- 优化了 YYY 逻辑

### 修复
- 修复了 ZZZ 问题

## [v1.0.0] - 2026-02-01

### 新增
- 初始版本发布

15. 检查版本号管理

检查项：

SKILL.md frontmatter 中如有 version 字段，是否与 CHANGELOG.md 最新版本一致
CHANGELOG.md 是否保留完整版本历史
README 和 marketplace 中的版本是否与 CHANGELOG.md 最新版本一致
source 是否未被不必要地强制要求（已有 homepage 时可省略）

注意：version 是公开发布推荐字段，不再视为违规；但 CHANGELOG.md 仍是版本历史来源，所有公开索引中的版本必须同步。

16. 检查可编排性设计

对于可能参与复杂工作流编排的技能，检查以下项：

检查项：

是否有明确的输入/输出声明（在 SKILL.md 中）
是否遵循单一职责原则（每个 Skill 只做一件事）
是否具有幂等性（多次执行结果相同）
复杂编排是否有 references/workflow.md

输入/输出声明格式：

## 输入/输出

### 输入
- 必需：`--input` 参数说明
- 可选：`--flag` 参数说明

### 输出
- 输出文件：`output/path.md` 说明
- 副作用：如创建目录、修改文件等

单一职责检查：

技能是否只完成一个核心任务
是否有多个不相关的功能混在一起

幂等性检查：

多次运行是否产生相同结果
是否有累积效应（如追加写入而非覆盖）

17. 检查依赖声明与防护

对于包含脚本的技能（scripts/ 目录非空），检查以下项：

检查项：

SKILL.md 是否声明了依赖（哪些功能需要额外安装）
脚本中的硬依赖是否有 try/except 包裹并给出安装提示
脚本中的可选依赖是否有 try/except 包裹并设置降级标志
requirements.txt 是否存在且只包含硬依赖（可选依赖不应列出）
SKILL.md 中依赖安装说明是否就近放置（在对应功能章节内，而非文档末尾）

判断标准：

无脚本的纯 prompt 技能：跳过此检查
有脚本但无外部依赖（仅用标准库）：在 SKILL.md 中注明"无需额外安装依赖"
有脚本且有外部依赖：必须通过上述所有检查项

生成审查报告

报告格式

# [skill-name] 格式审查报告

**审查时间**: YYYY-MM-DD HH:MM
**技能路径**: /path/to/skill

## 审查摘要

| 检查项 | 状态 | 问题数 |
|--------|------|--------|
| 目录结构 | ✅/⚠️/❌ | N |
| Frontmatter | ✅/⚠️/❌ | N |
| SKILL.md 行数 | ✅/⚠️ | N |
| 目录层级 | ✅/⚠️ | N |
| 文档一致性 | ✅/⚠️/❌ | N |
| 冗余内容 | ✅/⚠️/❌ | N |
| 配置文件 | ✅/⚠️/❌ | N |
| 技能协作 | ✅/⚠️/❌ | N |
| 模块化设计 | ✅/⚠️/❌ | N |
| 安全审计 | ✅/⚠️/❌ | N |
| 输出模式 | ✅/⚠️/❌ | N |
| 工作流模式 | ✅/⚠️/❌ | N |
| CHANGELOG | ✅/⚠️/❌ | N |
| 版本号管理 | ✅/⚠️/❌ | N |
| 可编排性 | ✅/⚠️/❌ | N |
| 依赖声明与防护 | ✅/⚠️/❌ | N |

## 详细问题

### 严重问题（必须修复）

1. **[问题标题]**
   - 位置: `文件路径:行号`
   - 规范: 违反的规范条款
   - 建议: 具体修复建议

### 建议优化

1. **[问题标题]**
   - 位置: `文件路径`
   - 建议: 优化建议

### 信息提示

- [提示信息]

## 建议操作

### 删除文件

| 文件路径 | 原因 |
|----------|------|
| `path/to/file.md` | 与 SKILL.md 重复 |
| `path/to/old.md` | 引用不存在的脚本 |

### 更新文件

| 文件路径 | 修改内容 |
|----------|----------|
| `SKILL.md` | 更新 description 格式 |
| `config.example.yaml` | 移除未使用的字段 |

### 新增文件

| 文件路径 | 用途 |
|----------|------|
| `assets/config.example.yaml` | 配置模板 |

## 审查完成

- 总问题数: N
- 严重问题: N
- 建议优化: N
- 信息提示: N

使用方法

用户提供要审查的技能路径，AI 执行以下步骤：

使用 Glob 列出技能目录所有文件
使用 Read 读取 SKILL.md 和其他关键文件
按检查清单逐项检查
生成结构化审查报告

规范参考

详细检查清单见 references/skill-standards.md

规范依据：docs/SKILL-DEV-GUIDE.md

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: Documentation
Author-declared agents: No explicit declaration found; this is not inferred or tested compatibility
Static check: 93 / 100 · heuristic scan, not runtime safety proof
Author / version / license: @cat-xierluo · v1.4.0 · MIT License - 详见 LICENSE.txt
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Env read
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。; 检出高风险片段：rm_rf_root

Output preview skill-lint.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# Skill 格式审查工具

对指定的 skill 进行格式合规性审查，生成结构化的审计报告。

## 审查流程

### 1. 扫描目标技能

使用 Glob 工具列出技能目录下的所有文件：

```
<skill-path>/
├── **/*.md
├── **/*.py
├── **/*.yaml
├── **/*.json
└── ...
```

### 2. 检查目录结构

验证是否符合标准目录结构：

```
skill-name/
├── SKILL.md          # 必需
├── LICENSE.txt       # 可选
├── CHANGELOG.md      # 可选（推荐）
├── TASKS.md          # 可选（开发上下文，保留）
├── DECISIONS.md      # 可选（开发上下文，保留）
├── references/       # 可选
├── scripts/          # 可选
├── templates/        # 可选
└── assets/           # 可选
```

**检查项**：
- [ ] SKILL.md 是否存在
- [ ] 是否有不规范的目录（如 `test/`、`docs/` 应改为 `references/`）
- [ ] 是否有不应提交的文件（如 `__pycache__/`、`.env`、`.DS_Store`）

**豁免文件**（以下文件为开发过程上下文，不应标记为不合规，不应建议删除）：
- `TASKS.md` — 任务追踪
- `DECISIONS.md` — 决策记录
- `CHANGELOG.md` — 变更日志

### 3. 检查 Frontmatter

解析 SKILL.md 的 YAML frontmatter：

```yaml
---
name: skill-name
description: 功能描述。本技能应在...时使用
version: "1.0.0"
license: MIT
author: 杨卫薪律师（微信ywxlaw）
homepage: https://github.com/cat-xierluo/legal-skills
---
```

**检查项**：
- [ ] `name` 字段是否存在且格式正确
- [ ] `description` 字段是否存在
- [ ] `description` 是否使用第三人称（"本技能应在...时使用"）
- [ ] `description` 是否包含触发场景描述
- [ ] `description` 是否包含负向触发条件（"不要用于..."）
- [ ] `description` 长度是否 ≤ 1024 字符
- [ ] 是否有 `license` 字段
- [ ] 如有 `version` 字段，是否与 `CHANGELOG.md` 最新版本一致
- [ ] 如有 README 或 marketplace 索引，版本是否同步

### 4. 检查 SKILL.md 行数

**检查项**：
- [ ] SKILL.md 行数是否 ≤ 500 行（超出应拆分到 references/）

### 5. 检查目录层级

**检查项**：
- [ ] `references/` 是否完全扁平（文件直接放在目录下，无子目录）
- [ ] `scripts/` 是否完全扁平（文件直接放在目录下，无子目录）
- [ ] `assets/` 是否完全扁平（文件直接放在目录下，无子目录）
- [ ] `templates/` 是否完全扁平（文件直接放在目录下，无子目录）

**注意**：所有二级目录（`references/`、`scripts/`、`assets/`、`templates/`）下禁止创建子目录，文件必须直接放在目录根。

### 6. 检查文档一致性

扫描所有 `.md` 文件，提取引用的文件路径：

**提取模式**：
- `scripts/xxx.py`
- `assets/xxx.yaml`
- `references/xxx.md`
- 相对路径引用

**检查项**：

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> 审查流程 → 1. 扫描目标技能 → 2. 检查目录结构 → 3. 检查 Frontmatter → 4. 检查 SKILL.md 行数 → 5. 检查目录层级
terms    -> 检查项 · 豁免文件 · 注意 · 提取模式 · CHANGELOG 格式规范 · 输入/输出声明格式 · 单一职责检查 · 幂等性检查
files/cmd -> test/ · docs/ · references/ · pycache/ · .env · .DSStore · TASKS.md · DECISIONS.md
body sha256 -> e2795c45d391

Decide Fit First

Design Intent

How To Use It

Boundaries And Review

Skill 格式审查工具

审查流程

1. 扫描目标技能

2. 检查目录结构

3. 检查 Frontmatter

4. 检查 SKILL.md 行数

5. 检查目录层级

6. 检查文档一致性

7. 检查冗余内容

8. 检查配置文件

9. 检查技能协作规范

10. 检查模块化设计

11. 检查安全审计

12. 检查输出模式

13. 检查工作流模式

14. 检查 CHANGELOG 规范

15. 检查版本号管理

16. 检查可编排性设计

17. 检查依赖声明与防护

生成审查报告

报告格式

使用方法

规范参考

Discussion