Back to Details

agent-skill-linter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Skill Linter

Agent Skill Linter

Checks agent skills for spec compliance and publishing readiness.
检查Agent Skill是否符合规范以及是否具备发布条件。

Expected Layout

预期目录结构

A well-structured skill repo separates agent-facing files (installed by 
npx skills add
) from repo artifacts:
my-skill/
├── skill/               ← only this dir is installed by npx
│   ├── SKILL.md
│   ├── references/
│   │   └── fix-templates.md
│   └── scripts/         ← skill-invoked scripts (optional)
│       └── main.py
├── src/                 ← linter/library source (not installed)
├── tests/
├── README.md
├── LICENSE
├── pyproject.toml
└── .github/
    └── workflows/
The lint target is the 
skill/
subdirectory (or repo root for older repos with no 
skill/
dir).
结构清晰的Skill仓库会将Agent所需文件（通过
npx skills add
安装）与仓库其他产物分开：
my-skill/
├── skill/               ← 仅该目录会通过npx安装
│   ├── SKILL.md
│   ├── references/
│   │   └── fix-templates.md
│   └── scripts/         ← Skill调用的脚本（可选）
│       └── main.py
├── src/                 ← 检查工具/库源码（不安装）
├── tests/
├── README.md
├── LICENSE
├── pyproject.toml
└── .github/
    └── workflows/
检查目标是
skill/
子目录（对于没有
skill/
目录的旧仓库，则为仓库根目录）。

Triage Workflow

检查流程

Target: the skill directory to lint — current directory (
.
) or a path provided by the user.
目标： 要检查的Skill目录——当前目录（
.
）或用户提供的路径。

Step 1 — Get the full picture

步骤1 — 查看完整检查结果

bash
./scripts/skill-lint.py check <target>
Review the output for errors and warnings; confirm the full picture before proceeding to Step 2.
bash
./scripts/skill-lint.py check <target>
查看输出中的错误和警告；在进入步骤2前确认整体情况。

Step 2 — Fix Errors first

步骤2 — 优先修复错误

Rule 1 (SKILL.md spec compliance) blocks publishing. Fix before anything else.
规则1（SKILL.md规范符合性）会阻止发布。需优先修复。

Step 3 — Auto-fix Warnings

步骤3 — 自动修复警告

bash
./scripts/skill-lint.py check <target> --fix
For fixable rules without CLI, use the templates in 
references/fix-templates.md
.
Confirm no auto-fixable warnings remain before continuing to Step 4.
bash
./scripts/skill-lint.py check <target> --fix
对于无法通过CLI自动修复的规则，使用
references/fix-templates.md
中的模板进行修复。
确认没有可自动修复的警告后，再进入步骤4。

Step 4 — Resolve remaining Warnings manually

步骤4 — 手动解决剩余警告

CSO description prefix (Rule 11), Python invocations (Rule 13), README-tier sections in SKILL.md (Rule 19) — see the rule table below.
CSO描述前缀（规则11）、Python调用方式（规则13）、SKILL.md中的README级章节（规则19）——请查看下方规则表格。

Step 5 — Semantic review: CSO signal

步骤5 — 语义评审：CSO信号

Rule 11 catches structural patterns but not meaning. Read the 
description
and 
name
frontmatter and ask: do they function purely as routing signals?
See 
references/semantic-rules.md
— Rules 12 and 18 for examples.
Flag the description if it:
  • Enumerates what the skill checks, handles, or supports
  • Reads as a feature summary or workflow overview
  • Contains elaboration labels (
    Triggers on:
    , 
    Use cases:
    , 
    Checks:
    ) or multiple sentences
  • Could be trimmed to one clause without losing routing precision
Flag the name if it reads as a noun phrase rather than an action — prefer gerunds (
creating-skills
, 
processing-pdfs
) over noun forms (
skill-creator
, 
pdf-processor
). Short well-known names (
pdf
, 
commit
) are fine.
A good description names the trigger condition only. Everything else belongs in the skill body.
Confirm the description and name function as pure routing signals before moving to Step 6.
规则11仅检查结构模式，不检查语义。阅读
description
和
name
前置元数据，并思考：它们是否仅作为路由信号发挥作用？
参考
references/semantic-rules.md
中的规则12和18示例。
若描述存在以下情况，则标记出来：
  • 列举了该Skill检查、处理或支持的内容
  • 读起来像功能总结或流程概述
  • 包含说明标签（如
    Triggers on:
    、
    Use cases:
    、
    Checks:
    ）或多个句子
  • 可精简为一个分句而不丢失路由精度
若名称是名词短语而非动作形式，则标记出来——优先使用动名词形式（如
creating-skills
、
processing-pdfs
）而非名词形式（如
skill-creator
、
pdf-processor
）。简短且广为人知的名称（如
pdf
、
commit
）除外。
优质的描述应仅说明触发条件。其他所有内容应放在Skill主体中。
确认描述和名称仅作为纯路由信号后，再进入步骤6。

Step 6 — Semantic review: starter prompts

步骤6 — 语义评审：启动提示

Rule 7 detects whether prompts exist, not whether they're useful. Read the Usage section starter prompts and ask: do they reflect genuine, distinct trigger scenarios?
Flag them if they:
  • Are vague or generic (e.g. 
    Use this skill
    , 
    Run the linter
    )
  • All describe the same scenario with minor wording variation
  • Don't reflect the range of contexts a real user would encounter
Confirm starter prompts cover genuinely distinct use cases before proceeding to Step 7.
规则7仅检测提示是否存在，不检查其实用性。阅读Usage章节中的启动提示，并思考：它们是否反映了真实、不同的触发场景？
若提示存在以下情况，则标记出来：
  • 模糊或通用（例如
    Use this skill
    、
    Run the linter
    ）
  • 所有描述都是同一场景的轻微措辞变体
  • 未覆盖真实用户会遇到的各类场景
确认启动提示覆盖了真正不同的使用场景后，再进入步骤7。

Step 7 — Semantic review: content overlap

步骤7 — 语义评审：内容重复

The linter does not check this. Ask: is the same information conveyed in different words across SKILL.md and README?
See 
references/semantic-rules.md
— Rule 8 for examples.
Flag paraphrased repetition. SKILL.md should be agent-focused (triage workflow, rules); README should be human-focused (installation, usage examples).
Confirm no paraphrased repetition remains before moving to Step 8.
检查工具不会检查此项。思考：SKILL.md和README中是否存在用不同语言表达相同信息的情况？
参考
references/semantic-rules.md
中的规则8示例。
标记这类改写后的重复内容。SKILL.md应聚焦Agent（检查流程、规则）；README应聚焦人类用户（安装说明、使用示例）。
确认没有改写后的重复内容后，再进入步骤8。

Step 8 — Semantic review: progressive disclosure

步骤8 — 语义评审：渐进式披露

Rule 15 flags known reference-tier keywords, but not all reactive content has a recognizable heading. Ask: would an agent look up this section reactively rather than read it upfront?
See 
references/semantic-rules.md
— Rule 16 for examples.
Flag sections for 
references/
if they:
  • Are reference material regardless of their heading name (e.g. "Background", "How It Works")
  • Are dense or conditional — even if short and not caught by Rule 15
  • Are step-specific detail blocks that bulk up the main workflow without being needed upfront
Confirm all reactive content has been moved to 
references/
before proceeding to Step 9.
规则15会标记已知的参考级关键词，但并非所有响应式内容都有可识别的标题。思考：Agent是否会在需要时才查阅该章节，而非提前阅读？
参考
references/semantic-rules.md
中的规则16示例。
若章节存在以下情况，则将其移至
references/
目录并标记：
  • 无论标题名称如何，都属于参考资料（例如"Background"、"How It Works"）
  • 内容密集或有条件限制——即使篇幅短且未被规则15捕获
  • 是步骤特定的详细块，会增加主流程的冗余内容且无需提前阅读
确认所有响应式内容已移至
references/
后，再进入步骤9。

Step 9 — Semantic review: multi-step workflow quality

步骤9 — 语义评审：多步骤流程质量

Only apply this step when the skill has a multi-step workflow (3+ 
### Step N
headings).
Read each step body and ask: does every substantive step state how the agent knows it is done?
See 
references/semantic-rules.md
— Rule 22 for examples.
Flag a step if its body describes only what to do with no exit condition, no gate phrase, no "proceed only when" signal. Trivially short steps (a single line) need no explicit gate.
Also ask: does the workflow include at least one step that checks actual tool output, not just verbal claims?
See 
references/semantic-rules.md
— Rule 23 for examples.
Flag the workflow if every step prescribes actions but none tells the agent to read what the tool actually returned.
Confirm both questions are satisfied before proceeding to Step 10.
仅当Skill包含多步骤流程（3个及以上
### Step N
标题）时，才执行此步骤。
阅读每个步骤的内容，并思考：每个实质性步骤是否说明了Agent如何判断该步骤已完成？
参考
references/semantic-rules.md
中的规则22示例。
若步骤仅描述要做什么，而未说明退出条件、 gate phrase或"仅当…时才继续"的信号，则标记该步骤。极短的步骤（仅一行）无需明确的完成信号。
同时思考：流程中是否至少有一个步骤是检查工具的实际输出，而非仅口头说明？
参考
references/semantic-rules.md
中的规则23示例。
若每个步骤仅规定操作，却未告知Agent读取工具的实际返回结果，则标记该流程。
确认上述两个问题都得到满足后，再进入步骤10。

Step 10 — Address Info items as polish

步骤10 — 处理信息类项以优化细节

Body length (Rule 9), non-standard dirs (Rule 10), skill isolation (Rule 17).
内容长度（规则9）、非标准目录（规则10）、Skill隔离性（规则17）。

What It Checks

检查内容

#RuleSeverityAuto-fix
1SKILL.md spec compliance (via skills-ref)Error—
2LICENSE exists, Apache-2.0 or MIT, current yearWarningPartial
3
metadata.author
in SKILL.md frontmatter		WarningYes
4README badges (CI, license, Agent Skills)WarningYes
5
.github/workflows/
has CI workflow		WarningYes
6README has Installation sectionWarningYes
7README has Usage section with starter prompts + CLI subsectionWarningPartial + Step 6
9SKILL.md body < 500 linesInfo—
10Non-standard directories flaggedInfo—
11CSO: description starts with "Use when..."WarningStep 5
13Python invocation consistency (
uv run python
in uv projects)		Warning—
14Progressive disclosure: embedded templates (4-backtick fences) → 
references/
WarningYes
15Progressive disclosure: reference-tier headings (Troubleshooting, FAQ, Advanced…) → 
references/
WarningYes + Step 8
17Skill isolation: SKILL.md at repo root alongside non-skill artifactsInfo—
19Division of labor: README-tier sections (Installation, Features, Getting Started…) in SKILL.mdWarning—
20Triage workflow has 3+ steps but no semantic review step (e.g. "Ask: does it…")InfoStep 5–9
21Python entry-point scripts in 
scripts/
lack PEP 723 inline dependency metadata		Warning—
编号规则严重程度自动修复
1SKILL.md规范符合性（通过skills-ref检查）错误—
2LICENSE文件存在，且为Apache-2.0或MIT协议，年份为当前年份警告部分支持
3SKILL.md前置元数据中包含
metadata.author
警告是
4README包含徽章（CI、许可证、Agent Skills）警告是
5
.github/workflows/
目录下有CI工作流		警告是
6README包含Installation章节警告是
7README包含Usage章节，其中包含启动提示和CLI子章节警告部分支持 + 步骤6
9SKILL.md主体内容少于500行信息—
10标记非标准目录信息—
11CSO：描述以"Use when..."开头警告步骤5
13Python调用一致性（uv项目中使用
uv run python
）		警告—
14渐进式披露：嵌入式模板（4反引号围栏）→ 移至
references/
警告是
15渐进式披露：参考级标题（Troubleshooting、FAQ、Advanced…）→ 移至
references/
警告是 + 步骤8
17Skill隔离性：SKILL.md位于仓库根目录，与非Skill产物共存信息—
19分工合理性：SKILL.md中包含README级章节（Installation、Features、Getting Started…）警告—
20检查流程包含3个及以上步骤，但无语义评审步骤（例如"Ask: does it…"）信息步骤5–9
21
scripts/
目录下的Python入口脚本缺少PEP 723内联依赖元数据		警告—

CLI Reference

CLI参考

bash
./scripts/skill-lint.py check .                            # Lint repo-root skill
./scripts/skill-lint.py check ./my-skill --fix             # Auto-fix fixable issues
./scripts/skill-lint.py check ./my-skill --format json     # JSON output for CI
Exit code 1 on errors, 0 otherwise.
bash
./scripts/skill-lint.py check .                            # 检查仓库根目录下的Skill
./scripts/skill-lint.py check ./my-skill --fix             # 自动修复可修复的问题
./scripts/skill-lint.py check ./my-skill --format json     # 输出JSON格式结果用于CI
存在错误时退出码为1，否则为0。