doodle

A linter for Claude SKILL.md files. Catches vague descriptions, oversized bodies, hardcoded paths, and silent trigger failures.

Overview

In late 2025 Anthropic introduced SKILL.md, a markdown format with YAML frontmatter that extends Claude with custom skills. By mid-2026 more than 5,000 skills have been published across community marketplaces. Anthropic's own issue tracker attributes 80% of skill trigger failures to vague descriptions (anthropics/skills#267), yet no static tooling for the format existed.

doodle closes that gap. Twelve static rules, each citing Anthropic's authoring guide or a documented community issue, plus a trigger-accuracy harness for measuring whether skills actually fire on natural-language prompts.

Install

pip install doodle-lint

Requires Python 3.10 or newer. Runtime dependencies: PyYAML, and tomli on Python 3.10. PyPI publication is pending; once complete, pip install doodle-lint will work.

Verify:

doodle --version
doodle --list-rules

Usage

# Scaffold a new skill that passes the linter out of the box
doodle init my-skill --eval          # creates ./my-skill/{SKILL.md,eval.yaml}

# Lint a single skill
doodle path/to/SKILL.md

# Lint a directory recursively
doodle ./skills

# JSON output for CI
doodle ./skills --format=json

# SARIF output for GitHub code scanning
doodle ./skills --format=sarif > doodle.sarif

# Apply auto-fixes for safe rules
doodle ./skills --fix

# Promote info to warning, warning to error
doodle --strict ./skills

# Disable a specific rule
doodle --ignore=body/emoji ./skills

# Explain a rule
doodle --explain desc/vague-trigger

Exit codes: 0 clean, 1 warnings, 2 errors, 3 tool error.

Phase 2: trigger-accuracy eval

# Requires: pip install ".[eval]", npm install -g promptfoo, ANTHROPIC_API_KEY
doodle eval --generate path/to/SKILL.md    # Draft a starter eval.yaml via Claude
doodle eval path/to/SKILL.md               # Run the eval, report the score
doodle eval path/to/SKILL.md --dry-run     # Preview the Promptfoo config

Full workflow: docs/EVAL.md.

VS Code / Cursor extension

The extension is published on the Open VSX Registry and works in Cursor, VSCodium, Windsurf, and VS Code with Open VSX enabled.

Features: real-time diagnostics, status bar with finding counts, hover messages linking to the rule catalog, quick-fix code actions for fixable rules, and a doodle eval bridge command.

Install from your editor's Extensions panel (search doodle), or via CLI:

# Cursor, VSCodium, Windsurf (Open VSX is the default gallery)
code --install-extension krishyaid-coder.doodle-lint

# Vanilla VS Code: install the VSIX from the latest GitHub Release
curl -L -o /tmp/doodle.vsix \
  https://github.com/krishyaid-coder/doodle/releases/latest/download/doodle-lint-0.2.0.vsix
code --install-extension /tmp/doodle.vsix

The extension shells out to the CLI installed above. Upgrading the CLI upgrades the extension's rules automatically.

Full extension docs: vscode/README.md.

CI (GitHub Action)

- uses: krishyaid-coder/doodle@v0
  with:
    path: ./skills
    strict: true
    fail-on: warning   # warning | error | never

Rules

Each rule cites either Anthropic's authoring documentation or a documented community issue. Full spec with examples, in-sample frequency, and citations: RULES.md.

Architecture

One Python package, six source files. Data flow: files → parser → rule registry → severity gate → formatter.

flowchart LR
    A[SKILL.md files] -->|read| B[Parser]
    B -->|ParsedSkill| C[Rule registry]
    Cfg[.doodle.toml] -->|custom rules<br/>+ overrides| C
    C -->|Finding stream| D[Severity gate]
    D -->|filtered| E{Formatter}
    E -->|text| F[stdout]
    E -->|json / sarif| G[CI / dashboard]

Components:

• parser: splits frontmatter from body and auto-detects the dialect.
• rule registry: runs built-in and custom rules, applies severity overrides, filters by dialect and per-path globs.
• custom rules: pattern and frontmatter-required rules loaded from .doodle.toml.
• formatter: renders findings as colored text, JSON, or SARIF.

Full component reference, sequence diagrams, and extension points: docs/ARCHITECTURE.md.

Dialects

Two SKILL.md dialects exist in the wild. doodle auto-detects.

• anthropic: minimal frontmatter (name, description, optional license). Used by anthropics/skills.
• extended: community schema with version, author, tags, allowed-tools. Used by alirezarezvani/claude-skills, jeremylongshore/claude-code-plugins-plus-skills, and DietrichGebert/ponytail.

Some rules apply to both. Others are dialect-scoped.

Custom rules (teams and enterprise)

Drop a .doodle.toml in your project root. No Python required for regex-based rules or frontmatter requirements.

[options]
dialect = "extended"
fail-on = "warning"

[severity]
"body/emoji" = "off"
"body/too-long" = "info"

[[paths]]
glob = "**/experiments/**/SKILL.md"
disabled = ["desc/vague-trigger", "body/too-long"]

[[rules]]
id = "acme/no-customer-pii"
kind = "pattern"
pattern = "(?i)\\bcustomer_[a-z]+\\b"
applies-to = "body"
severity = "error"
message = "Customer PII tokens are not allowed in skills."
suggestion = "Use 'user_<role>' instead."

[[rules]]
id = "acme/require-team-tag"
kind = "frontmatter-required"
fields = ["team", "data-classification"]
severity = "error"
message = "Internal skills must declare team and data-classification."

Config is discovered by walking up the directory tree. Force a path with --config. For rules requiring Python logic, see docs/EXTENDING.md.

Roadmap

Validation

I ran doodle against 62 published SKILL.md files from the most-popular repositories: DietrichGebert/ponytail (33k stars), anthropics/skills, obra/superpowers, and alirezarezvani/claude-skills. 82 percent of the sample had at least one quality finding, including Anthropic's own first-party skills and ponytail's reference skill.

Full methodology, per-repository breakdown, and raw data: docs/QUALITY_REPORT.md.

Documentation

• Quality Report: findings across 62 published skills, with methodology and raw data
• Architecture: diagrams, components, extension points, trade-offs
• Rule spec: every rule with citation, example, and in-sample frequency
• Extending: add a rule in Python or via .doodle.toml
• Eval guide: Phase 2 trigger-accuracy workflow
• VS Code extension: editor integration reference
• Why doodle: impact argument, honest risk assessment
• Contributing: ground rules and PR checklist

License

MIT. The CLI and rule-set are MIT-licensed permanently. Any future hosted services will be a separate repository under a separate license.