# drskill: lint claude skills

> Source: <https://perrotta.dev/2026/07/drskill-lint-claude-skills/>
> Published: 2026-07-28 17:09:34+00:00

♠ I found drskill through Drew Breunig’s post about
[managing an agent’s loadout](https://www.dbreunig.com/2026/07/24/manage-your-agent-s-loadout-with-dr-skill.html).

**Problem statement**: lint skills bundled in a Claude Code plugin with
[ drskill](https://github.com/dbreunig/drskill).

Running it through `uvx`

is easy enough:

```
% uvx drskill scan --detailed
drskill scan — 3 harnesses (10 more empty), 9 skills
...
0 errors, 5 warnings (5 new) · token counts are approximate
```

But none of this repository’s 11 skills appeared. The
[known limitation](https://github.com/dbreunig/drskill#known-limitations) explains
why:

Claude Code skills bundled inside plugins are not scanned yet.

I projected the plugin’s skill directory into the plain `.claude/skills`

layout
that drskill understands via `Justfile`

:

``` bash
# Check skills with drskill
doctor:
    #!/usr/bin/env bash
    set -euo pipefail
    tmp=$(mktemp -d)
    trap 'trash "$tmp"' EXIT
    mkdir -p "$tmp/project/.claude/skills" "$tmp/home"
    for skill in "$PWD"/plugins/thiagowfx/skills/*; do
      ln -s "$skill" "$tmp/project/.claude/skills/$(basename "$skill")"
    done
    uv_cache=$(uv cache dir)
    cd "$tmp/project"
    HOME="$tmp/home" UV_CACHE_DIR="$uv_cache" uvx drskill scan --ci --harness claude-code
```

The temporary `HOME`

excludes unrelated global skills. Reusing uv’s cache avoids
redownloading drskill there. `--ci`

makes warnings fail the recipe.

The first isolated scan found four warnings:

```
drskill scan — 1 harness, 11 skills

WARNINGS
  [e91d] new frontmatter-angle-brackets: 'bloggify' ...
  [a551] new frontmatter-angle-brackets: 'gha' ...
  [6335] new frontmatter-angle-brackets: 'new-apkbuild' ...
  [206e] new missing-activation: 2 skills never say when to use them ...

0 errors, 4 warnings (4 new) · token counts are approximate
exit=2
```

The fixes were small: remove angle brackets from `argument-hint`

values and add
explicit activation conditions to `catchup`

and `handoff`

:

```
-argument-hint: "<url>"
+argument-hint: "url"

-description: Create portable handoff document for another agent or harness to continue current work.
+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.
```

Now the repository has its own linter:

```
% just doctor
drskill scan — 1 harness, 11 skills

No findings.
0 errors, 0 warnings · token counts are approximate
```

Restoring `<url>`

temporarily made `just doctor`

exit 2 again, so future warnings
will break the check. I should add it to CI at some point.

🤖 *Drafted with *

`/bloggify`

.— § —

Reply via [email](mailto:serendipity@perrotta.dev?subject=Reply to: drskill: lint claude skills)