skilllint Skill 技能

skilllint 是 AI 编码 Agent 插件与技能的静态分析 linter，支持 Claude Code、Cursor、OpenAI Codex 及任何兼容 agentskills.io 标准的平台。它在代码合并前捕获结构性问题，防止运行时静默故障。

技能简介

skilllint 对 AI Agent 的插件、技能、代理和命令文件进行结构与内容验证。它检查破损引用、缺失 frontmatter、超大技能块、无效 hook 配置等问题，在实际运行失败之前拦截。不同于运行时测试，skilllint 通过静态分析完成检查，不需要启动 Agent，不需要网络调用，适合作为 CI 流程的第一步。

核心能力

• 45+ 验证规则，覆盖 frontmatter、skill token 限制、hook 配置、跨插件命名空间引用、plugin.json 注册完整性等
• 三大平台适配器：Claude Code（claude-code）、Cursor（cursor）、OpenAI Codex（codex），并通过 Python 入口点支持第三方适配器
• 自动修复：部分问题支持 --fix 自动修复，减少人工干预
• Token 计数报告：检测 SKILL.md 是否超出 8192 token 建议上限
• GitHub Action 一键集成：bitflight-devops/skilllint Action 零配置接入 CI
• Pre-commit Hook：提交前自动验证，提前发现问题
• 离线文档缓存：skilllint docs fetch 缓存厂商文档页面，离线也可查阅 Claude Code 等平台文档
• 损坏内部链接检测：LK001 规则检测 markdown 文件中断开的内部引用

安装配置

方式一：pip 安装

pip install skilllint
# 或使用 uv
uv add skilllint          # 添加到项目
uv tool install skilllint # 全局安装

要求：Python 3.11–3.14

方式二：GitHub Action

- uses: bitflight-devops/skilllint@v1.7.0
  with:
    paths: "plugins/ .claude/"
    platform: "claude-code"
    show-summary: "true"

方式三：Pre-commit Hook

在 .pre-commit-config.yaml 中添加：

repos:
  - repo: https://github.com/bitflight-devops/skilllint
    rev: v1.7.0
    hooks:
      - id: skilllint

使用步骤

1. 安装 skilllint（pip / uv / GitHub Action 任选）

2. 运行基础检查：

   skilllint check plugins/my-plugin

3. 查看详细输出：

   skilllint check --verbose plugins/

4. 自动修复可修复的问题：

   skilllint check --fix plugins/

5. 生成汇总报告：

   skilllint check --show-summary plugins/

6. 统计 Token 数量：

   skilllint check --tokens-only .claude/CLAUDE.md

适用场景

• CI/CD 流水线：每次 PR 自动验证插件结构，防止有问题的 skill 进入生产
• 团队协作：统一 skill 编写规范，避免个人风格差异导致维护困难
• Plugin 开发：在发布前检查 plugin.json 注册完整性、hook 脚本存在性
• Cursor/Claude Code 环境迁移：将现有 skill 迁移到新平台时，验证兼容性
• 大型 Skill 库维护：token 上限检查防止单个 skill 过大影响加载性能
• 第三方 skill 审核：引入外部 skill 前，用 skilllint 验证其结构是否符合规范

适用人群

• AI 编码 Agent 开发者：使用 Claude Code、Cursor、Codex 的工程师
• 平台构建者：搭建内部 Agent 平台，需要统一技能规范的技术负责人
• DevOps 工程师：负责 AI Agent 相关 CI/CD 流程的工程师
• Skill 市场运营者：需要批量审核第三方提交技能包质量的团队

工作原理

skilllint 读取目标目录的 SKILL.md、AGENTS.md、plugin.json、hook 脚本等文件，根据 frontmatter schema 和平台规范进行结构验证。规则分为多个类别：FM（frontmatter）、SK（skill 内容质量）、PL（plugin 结构）、HK（hook 配置）、NR（命名空间引用）、TC（token 计数）等。平台适配器负责将通用规则映射到各平台的特有字段和约束。--fix 模式下，skilllint 直接修改可安全修复的文件（如补充 frontmatter 缺失字段）。

官方链接

• PyPI：https://pypi.org/project/skilllint/
• GitHub：https://github.com/bitflight-devops/skilllint
• 规则文档：skilllint rules / skilllint rule
• agentskills.io：https://agentskills.io