{"slug": "drskill-lint-claude-skills", "title": "drskill: lint claude skills", "summary": "Developer Thiago Perrotta used the drskill linter to scan Claude Code skills bundled in a plugin, working around a known limitation by symlinking the plugin's skill directory into a temporary .claude/skills layout. The scan found four warnings, including frontmatter angle brackets and missing activation conditions, which Perrotta fixed by editing the skill files. The repository now passes `just doctor` with zero errors and warnings, and the check will fail on future warnings.", "body_md": "♠ I found drskill through Drew Breunig’s post about\n[managing an agent’s loadout](https://www.dbreunig.com/2026/07/24/manage-your-agent-s-loadout-with-dr-skill.html).\n\n**Problem statement**: lint skills bundled in a Claude Code plugin with\n[ drskill](https://github.com/dbreunig/drskill).\n\nRunning it through `uvx`\n\nis easy enough:\n\n```\n% uvx drskill scan --detailed\ndrskill scan — 3 harnesses (10 more empty), 9 skills\n...\n0 errors, 5 warnings (5 new) · token counts are approximate\n```\n\nBut none of this repository’s 11 skills appeared. The\n[known limitation](https://github.com/dbreunig/drskill#known-limitations) explains\nwhy:\n\nClaude Code skills bundled inside plugins are not scanned yet.\n\nI projected the plugin’s skill directory into the plain `.claude/skills`\n\nlayout\nthat drskill understands via `Justfile`\n\n:\n\n``` bash\n# Check skills with drskill\ndoctor:\n    #!/usr/bin/env bash\n    set -euo pipefail\n    tmp=$(mktemp -d)\n    trap 'trash \"$tmp\"' EXIT\n    mkdir -p \"$tmp/project/.claude/skills\" \"$tmp/home\"\n    for skill in \"$PWD\"/plugins/thiagowfx/skills/*; do\n      ln -s \"$skill\" \"$tmp/project/.claude/skills/$(basename \"$skill\")\"\n    done\n    uv_cache=$(uv cache dir)\n    cd \"$tmp/project\"\n    HOME=\"$tmp/home\" UV_CACHE_DIR=\"$uv_cache\" uvx drskill scan --ci --harness claude-code\n```\n\nThe temporary `HOME`\n\nexcludes unrelated global skills. Reusing uv’s cache avoids\nredownloading drskill there. `--ci`\n\nmakes warnings fail the recipe.\n\nThe first isolated scan found four warnings:\n\n```\ndrskill scan — 1 harness, 11 skills\n\nWARNINGS\n  [e91d] new frontmatter-angle-brackets: 'bloggify' ...\n  [a551] new frontmatter-angle-brackets: 'gha' ...\n  [6335] new frontmatter-angle-brackets: 'new-apkbuild' ...\n  [206e] new missing-activation: 2 skills never say when to use them ...\n\n0 errors, 4 warnings (4 new) · token counts are approximate\nexit=2\n```\n\nThe fixes were small: remove angle brackets from `argument-hint`\n\nvalues and add\nexplicit activation conditions to `catchup`\n\nand `handoff`\n\n:\n\n```\n-argument-hint: \"<url>\"\n+argument-hint: \"url\"\n\n-description: Create portable handoff document for another agent or harness to continue current work.\n+description: Create a portable handoff document for another agent or harness to continue current work. Use when the user asks for a handoff, continuation brief, or context transfer.\n```\n\nNow the repository has its own linter:\n\n```\n% just doctor\ndrskill scan — 1 harness, 11 skills\n\nNo findings.\n0 errors, 0 warnings · token counts are approximate\n```\n\nRestoring `<url>`\n\ntemporarily made `just doctor`\n\nexit 2 again, so future warnings\nwill break the check. I should add it to CI at some point.\n\n🤖 *Drafted with *\n\n`/bloggify`\n\n.— § —\n\nReply via [email](mailto:serendipity@perrotta.dev?subject=Reply to: drskill: lint claude skills)", "url": "https://wpnews.pro/news/drskill-lint-claude-skills", "canonical_source": "https://perrotta.dev/2026/07/drskill-lint-claude-skills/", "published_at": "2026-07-28 17:09:34+00:00", "updated_at": "2026-08-04 09:04:09.795889+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["drskill", "Drew Breunig", "Claude Code", "Thiago Perrotta", "Justfile", "uvx"], "alternates": {"html": "https://wpnews.pro/news/drskill-lint-claude-skills", "markdown": "https://wpnews.pro/news/drskill-lint-claude-skills.md", "text": "https://wpnews.pro/news/drskill-lint-claude-skills.txt", "jsonld": "https://wpnews.pro/news/drskill-lint-claude-skills.jsonld"}}