Skill Checker

skill-checker audits a SKILL.md against a platform contract and strict publication policy, statically scans its directory, and generates an offline HTML report.

• Author: oahcfly
• Version: 1.2.1
• License: MIT
• Official rules verified: 2026-09-12

Install and run

Requires Python 3.10+ and PyYAML. Replace the installation placeholder with the actual skill directory. $MyInvocation.MyCommand.Path does not locate a skill when pasted into an interactive shell.

$SkillDir = "C:\path\to\skill-checker"
python -c "import yaml; print(yaml.__version__)"
python "$SkillDir\scripts\check_skill.py" "C:\path\to\target-skill" --profile codex --out ".\reports\skill-report.html"

If PyYAML is unavailable, install the exact audited dependency only after approving the environment change:

python -m pip install -r "$SkillDir\requirements.txt"

Accepts a directory or its SKILL.md, including absolute paths outside this repository. Without --out, writes a timestamped report in the current directory. Reports under reports/ are ignored by Git.

Platform modes

--profile	Use for
standard	Default portable Agent Skills contract
codex	Codex skills, including agents/openai.yaml
claude-code	Claude Code local/plugin skills and frontmatter extensions
claude-upload	Portable frontmatter for claude.ai / Skills API / packaging

The profile is explicit, not guessed from the folder. Upload mode is not exhaustive API validation. No target code, hooks, dynamic shell commands or models are executed. Installed-host versions and real trigger behavior are not tested.

Strict project requirements

All profiles require the six common fields: name, description, license, compatibility, metadata, allowed-tools. Official optional fields remain mandatory under project policy, separately from official specification errors.

Require these metadata strings:

metadata:
  author: example-team
  version: "1.0.0"
  last-updated: "2026-09-12"
  keywords: documentation, review
  description_en: Review documents when checking publication readiness.
  description_zh: 检查文档，适用于发布前审阅。

Codex mode additionally requires agents/openai.yaml with interface.display_name, short_description, default_prompt and explicit boolean policy.allow_implicit_invocation. Example:

interface:
  display_name: "Document Review"
  short_description: "Review document readiness"
  default_prompt: "Use $document-review to check this document."
policy:
  allow_implicit_invocation: false

Behavioral extensions, icons and tool dependencies are checked if supplied. Do not invent dependencies or enable hooks/fork/background behavior to fill optional fields.

Results and report

The offline report separates specification/platform, project policy, quality and security. Chinese is the default; English, search/category/severity filters, expandable evidence, coverage details and printing are supported. Untranslated findings retain their original wording.

• Any severe finding or security block: fail / 不通过.
• Otherwise security review: review / 待复核.
• Otherwise pass / 通过. Quality warnings alone do not fail.

Security policy: high/critical or two medium findings block; one medium or incomplete coverage requires review.

python .\scripts\check_skill.py . --profile codex --out .\reports\self-audit.html --fail-on-audit

A completed command exits 0 by default, even if the audit fails. With --fail-on-audit, failure or security review exits 1. Invalid inputs and parse errors generate reports.

Migration from 1.1

• Official optional fields remain mandatory but missing values use policy.* instead of misleading spec.* identifiers.
• Move top-level description_en/description_zh into metadata for portability.
• One hard violation now fails; the former two-severe threshold is removed.
• Short descriptions and thin bodies are quality warnings; empty bodies remain severe.
• Safe YAML supports multiline strings, lists and nested maps, with duplicate-key rejection.
• Local YAML limits: 64 KiB, depth 32, no aliases; SKILL.md input: 1 MiB. These are checker limits, not official limits.
• Static scanning remains bounded: 150 files, 256 KiB per file, 5 MiB total. Skips symlinks, binaries, archives, dependencies, build output and caches. Coverage is reported; scanning cannot prove safety.
• .clawhubignore excludes test attack strings, reports and browser artifacts from the marketplace bundle. Review the exact local file list before publishing.

Development

python -m unittest discover -s .\tests -p "test_*.py"

Implementation: scripts/check_skill.py (CLI/audit), platform_rules.py (contracts/policy), yaml_support.py (safe parsing), security_scan.py (static scan), report.py and report_template.html (offline report).

See the checklist for exact rules, source links and limitations. Keep tests, documentation and report semantics consistent when updating requirements.