drskill 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. drskill-0.3.0/PKG-INFO +6 -0
  2. drskill-0.3.0/pyproject.toml +18 -0
  3. drskill-0.2.0/.claude/scheduled_tasks.lock +0 -1
  4. drskill-0.2.0/LICENSE +0 -21
  5. drskill-0.2.0/PKG-INFO +0 -175
  6. drskill-0.2.0/README.md +0 -161
  7. drskill-0.2.0/docs/superpowers/plans/2026-07-19-drskill-v0.1.md +0 -3125
  8. drskill-0.2.0/docs/superpowers/plans/2026-07-20-detailed-scan-linked-provenance.md +0 -528
  9. drskill-0.2.0/docs/superpowers/plans/2026-07-20-tier2-heuristics.md +0 -955
  10. drskill-0.2.0/docs/superpowers/plans/2026-07-20-tier3-injection.md +0 -1812
  11. drskill-0.2.0/docs/superpowers/plans/2026-07-20-triage-ux.md +0 -1147
  12. drskill-0.2.0/docs/superpowers/specs/2026-07-19-drskill-v0.1-design.md +0 -232
  13. drskill-0.2.0/docs/superpowers/specs/2026-07-20-detailed-scan-and-linked-provenance-design.md +0 -63
  14. drskill-0.2.0/docs/superpowers/specs/2026-07-20-granular-verification-design.md +0 -43
  15. drskill-0.2.0/docs/superpowers/specs/2026-07-20-report-triage-design.md +0 -87
  16. drskill-0.2.0/docs/superpowers/specs/2026-07-20-review-command-design.md +0 -73
  17. drskill-0.2.0/docs/superpowers/specs/2026-07-20-tier2-heuristics-design.md +0 -143
  18. drskill-0.2.0/docs/superpowers/specs/2026-07-20-tier3-injection-design.md +0 -113
  19. drskill-0.2.0/docs/superpowers/specs/2026-07-21-explain-command-design.md +0 -102
  20. drskill-0.2.0/drskill.toml +0 -16
  21. drskill-0.2.0/initial_design_doc.md +0 -191
  22. drskill-0.2.0/pyproject.toml +0 -33
  23. drskill-0.2.0/scripts/corpus.py +0 -115
  24. drskill-0.2.0/src/drskill/__init__.py +0 -0
  25. drskill-0.2.0/src/drskill/checks/__init__.py +0 -82
  26. drskill-0.2.0/src/drskill/checks/budget.py +0 -40
  27. drskill-0.2.0/src/drskill/checks/duplicates.py +0 -103
  28. drskill-0.2.0/src/drskill/checks/filesystem.py +0 -36
  29. drskill-0.2.0/src/drskill/checks/heuristics.py +0 -249
  30. drskill-0.2.0/src/drskill/checks/injection.py +0 -523
  31. drskill-0.2.0/src/drskill/checks/lockfile.py +0 -129
  32. drskill-0.2.0/src/drskill/checks/shadowing.py +0 -144
  33. drskill-0.2.0/src/drskill/checks/spec.py +0 -108
  34. drskill-0.2.0/src/drskill/cli.py +0 -432
  35. drskill-0.2.0/src/drskill/data/__init__.py +0 -0
  36. drskill-0.2.0/src/drskill/data/harnesses.toml +0 -973
  37. drskill-0.2.0/src/drskill/discovery.py +0 -96
  38. drskill-0.2.0/src/drskill/harnesses.py +0 -62
  39. drskill-0.2.0/src/drskill/interactive.py +0 -48
  40. drskill-0.2.0/src/drskill/ledger.py +0 -119
  41. drskill-0.2.0/src/drskill/models.py +0 -79
  42. drskill-0.2.0/src/drskill/pipeline.py +0 -45
  43. drskill-0.2.0/src/drskill/report.py +0 -259
  44. drskill-0.2.0/src/drskill/resolution.py +0 -222
  45. drskill-0.2.0/src/drskill/state.py +0 -42
  46. drskill-0.2.0/src/drskill/text.py +0 -113
  47. drskill-0.2.0/src/drskill/tokens.py +0 -30
  48. drskill-0.2.0/tests/__init__.py +0 -0
  49. drskill-0.2.0/tests/conformance/cases/clean-pair/expect.toml +0 -79
  50. drskill-0.2.0/tests/conformance/cases/clean-pair/tree/.claude/skills/docx-report/SKILL.md +0 -5
  51. drskill-0.2.0/tests/conformance/cases/clean-pair/tree/.claude/skills/git-helper/SKILL.md +0 -5
  52. drskill-0.2.0/tests/conformance/cases/corpus-activation/LICENSE-NOTE.md +0 -10
  53. drskill-0.2.0/tests/conformance/cases/corpus-activation/expect.toml +0 -20
  54. drskill-0.2.0/tests/conformance/cases/corpus-activation/tree/.claude/skills/frontend-design/SKILL.md +0 -5
  55. drskill-0.2.0/tests/conformance/cases/corpus-activation/tree/.claude/skills/grok/SKILL.md +0 -5
  56. drskill-0.2.0/tests/conformance/cases/corpus-activation/tree/.claude/skills/webapp-testing/SKILL.md +0 -5
  57. drskill-0.2.0/tests/conformance/cases/corpus-injection/LICENSE-NOTE.md +0 -10
  58. drskill-0.2.0/tests/conformance/cases/corpus-injection/expect.toml +0 -21
  59. drskill-0.2.0/tests/conformance/cases/corpus-injection/tree/.claude/skills/gpu-cloud/SKILL.md +0 -5
  60. drskill-0.2.0/tests/conformance/cases/corpus-injection/tree/.claude/skills/gpu-cloud/references/troubleshooting.md +0 -3
  61. drskill-0.2.0/tests/conformance/cases/corpus-injection/tree/.claude/skills/metrics-optimizer/SKILL.md +0 -5
  62. drskill-0.2.0/tests/conformance/cases/corpus-injection/tree/.claude/skills/metrics-optimizer/scripts/deep-dive.mjs +0 -1
  63. drskill-0.2.0/tests/conformance/cases/corpus-injection/tree/.claude/skills/tool-caller/SKILL.md +0 -5
  64. drskill-0.2.0/tests/conformance/cases/corpus-injection/tree/.claude/skills/trading-client/SKILL.md +0 -5
  65. drskill-0.2.0/tests/conformance/cases/corpus-injection/tree/.claude/skills/trading-client/scripts/client.py +0 -2
  66. drskill-0.2.0/tests/conformance/cases/diverged-copies/expect.toml +0 -7
  67. drskill-0.2.0/tests/conformance/cases/diverged-copies/tree/.claude/skills/geo/SKILL.md +0 -5
  68. drskill-0.2.0/tests/conformance/cases/diverged-copies/tree/.pi/skills/geo/SKILL.md +0 -5
  69. drskill-0.2.0/tests/conformance/cases/exact-dup-cross-harness/expect.toml +0 -3
  70. drskill-0.2.0/tests/conformance/cases/exact-dup-cross-harness/tree/.claude/skills/fmt/SKILL.md +0 -5
  71. drskill-0.2.0/tests/conformance/cases/exact-dup-cross-harness/tree/.pi/skills/fmt/SKILL.md +0 -5
  72. drskill-0.2.0/tests/conformance/cases/generic-description/expect.toml +0 -3
  73. drskill-0.2.0/tests/conformance/cases/generic-description/tree/.claude/skills/vague-helper/SKILL.md +0 -5
  74. drskill-0.2.0/tests/conformance/cases/injection-hostile/expect.toml +0 -30
  75. drskill-0.2.0/tests/conformance/cases/injection-hostile/tree/.claude/skills/data-helper/SKILL.md +0 -15
  76. drskill-0.2.0/tests/conformance/cases/injection-hostile/tree/.claude/skills/data-helper/references/notes.md +0 -1
  77. drskill-0.2.0/tests/conformance/cases/injection-hostile/tree/.claude/skills/data-helper/scripts/setup.sh +0 -3
  78. drskill-0.2.0/tests/conformance/cases/missing-activation/expect.toml +0 -7
  79. drskill-0.2.0/tests/conformance/cases/missing-activation/tree/.claude/skills/formatter/SKILL.md +0 -5
  80. drskill-0.2.0/tests/conformance/cases/near-dup-pair/expect.toml +0 -3
  81. drskill-0.2.0/tests/conformance/cases/near-dup-pair/tree/.claude/skills/report-writer/SKILL.md +0 -7
  82. drskill-0.2.0/tests/conformance/cases/near-dup-pair/tree/.claude/skills/status-writer/SKILL.md +0 -7
  83. drskill-0.2.0/tests/conformance/cases/near-dup-pair/tree/drskill.toml +0 -2
  84. drskill-0.2.0/tests/conformance/cases/opposing-imperatives/expect.toml +0 -3
  85. drskill-0.2.0/tests/conformance/cases/opposing-imperatives/tree/.claude/skills/tabs-fan/SKILL.md +0 -5
  86. drskill-0.2.0/tests/conformance/cases/opposing-imperatives/tree/.claude/skills/tabs-foe/SKILL.md +0 -5
  87. drskill-0.2.0/tests/conformance/cases/over-budget/expect.toml +0 -7
  88. drskill-0.2.0/tests/conformance/cases/over-budget/tree/.claude/skills/chatty/SKILL.md +0 -6
  89. drskill-0.2.0/tests/conformance/cases/over-budget/tree/drskill.toml +0 -3
  90. drskill-0.2.0/tests/conformance/cases/overlap-pileup/expect.toml +0 -3
  91. drskill-0.2.0/tests/conformance/cases/overlap-pileup/tree/.claude/skills/doc-chapters/SKILL.md +0 -5
  92. drskill-0.2.0/tests/conformance/cases/overlap-pileup/tree/.claude/skills/doc-pages/SKILL.md +0 -5
  93. drskill-0.2.0/tests/conformance/cases/overlap-pileup/tree/.claude/skills/doc-summaries/SKILL.md +0 -5
  94. drskill-0.2.0/tests/conformance/cases/spec-violations/expect.toml +0 -7
  95. drskill-0.2.0/tests/conformance/cases/spec-violations/tree/.claude/skills/no-desc/SKILL.md +0 -4
  96. drskill-0.2.0/tests/conformance/cases/spec-violations/tree/.claude/skills/wrong-name/SKILL.md +0 -5
  97. drskill-0.2.0/tests/conformance/test_conformance.py +0 -33
  98. drskill-0.2.0/tests/test_checks_budget.py +0 -39
  99. drskill-0.2.0/tests/test_checks_duplicates.py +0 -143
  100. drskill-0.2.0/tests/test_checks_filesystem.py +0 -47
  101. drskill-0.2.0/tests/test_checks_heuristics.py +0 -266
  102. drskill-0.2.0/tests/test_checks_injection.py +0 -436
  103. drskill-0.2.0/tests/test_checks_lockfile.py +0 -125
  104. drskill-0.2.0/tests/test_checks_shadowing.py +0 -190
  105. drskill-0.2.0/tests/test_checks_spec.py +0 -95
  106. drskill-0.2.0/tests/test_cli_commands.py +0 -287
  107. drskill-0.2.0/tests/test_cli_review.py +0 -160
  108. drskill-0.2.0/tests/test_cli_scan.py +0 -190
  109. drskill-0.2.0/tests/test_discovery.py +0 -115
  110. drskill-0.2.0/tests/test_harnesses.py +0 -67
  111. drskill-0.2.0/tests/test_interactive.py +0 -44
  112. drskill-0.2.0/tests/test_ledger.py +0 -142
  113. drskill-0.2.0/tests/test_models.py +0 -65
  114. drskill-0.2.0/tests/test_report.py +0 -361
  115. drskill-0.2.0/tests/test_resolution.py +0 -313
  116. drskill-0.2.0/tests/test_smoke.py +0 -34
  117. drskill-0.2.0/tests/test_state.py +0 -51
  118. drskill-0.2.0/tests/test_text.py +0 -75
  119. drskill-0.2.0/tests/test_tokens.py +0 -30
  120. drskill-0.2.0/uv.lock +0 -646
  121. {drskill-0.2.0 → drskill-0.3.0}/.gitignore +0 -0
drskill-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,6 @@
1
+ Metadata-Version: 2.4
2
+ Name: drskill
3
+ Version: 0.3.0
4
+ Summary: brew doctor for your AI agent's skill loadout
5
+ Requires-Python: >=3.11
6
+ Requires-Dist: drskill-core[deep]==0.3.0
@@ -0,0 +1,18 @@
1
+ # The `drskill` package everyone installs. It is a metapackage: no code,
2
+ # just drskill-core plus the deep extra, so the default install includes
3
+ # everything and CI can opt down to drskill-core. Its version must always
4
+ # equal drskill-core's; /release bumps and publishes both, core first.
5
+
6
+ [project]
7
+ name = "drskill"
8
+ version = "0.3.0"
9
+ description = "brew doctor for your AI agent's skill loadout"
10
+ requires-python = ">=3.11"
11
+ dependencies = ["drskill-core[deep]==0.3.0"]
12
+
13
+ [build-system]
14
+ requires = ["hatchling"]
15
+ build-backend = "hatchling.build"
16
+
17
+ [tool.hatch.build.targets.wheel]
18
+ bypass-selection = true
@@ -1 +0,0 @@
1
- {"sessionId":"571cac5f-2305-47b0-b52f-d79460f2f086","pid":38755,"procStart":"Mon Jul 20 03:35:27 2026","acquiredAt":1784522584769}
drskill-0.2.0/LICENSE DELETED
@@ -1,21 +0,0 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Drew Breunig
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
drskill-0.2.0/PKG-INFO DELETED
@@ -1,175 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: drskill
3
- Version: 0.2.0
4
- Summary: brew doctor for your AI agent's skill loadout
5
- License-File: LICENSE
6
- Requires-Python: >=3.11
7
- Requires-Dist: pydantic>=2
8
- Requires-Dist: pyyaml>=6
9
- Requires-Dist: rich>=13
10
- Requires-Dist: tiktoken>=0.7
11
- Requires-Dist: tomli-w>=1
12
- Requires-Dist: typer>=0.12
13
- Description-Content-Type: text/markdown
14
-
15
- ### They Call Me Dr. Skill
16
-
17
- drskill is `brew doctor` for your agent's skill loadout. It looks at every coding agent installed on your machine or configured in your repo, works out exactly which skills each one loads, and checks that set for problems: skills that shadow each other, skills loaded twice, duplicate or near-duplicate skills, skills that break the SKILL.md spec, broken symlinks, drift against your lockfile, and skills that burn too many tokens. Every problem it reports ends in a command: a fix command or a command to acknowledge the problem and move on. drskill only reads your files. It never installs, edits, or deletes a skill, and it makes zero calls to an LLM.
18
-
19
- ## Install
20
-
21
- ```
22
- uv tool install drskill
23
- ```
24
-
25
- ## Quick start
26
-
27
- Run a scan from the root of a project:
28
-
29
- ```
30
- drskill scan
31
- ```
32
-
33
- This detects every coding agent it can find, resolves each one's effective skill set, and prints a report grouped by severity. Each finding names the harnesses it affects and ends in a fix command or an ack command.
34
-
35
- Write a starter ledger file with default budgets and thresholds:
36
-
37
- ```
38
- drskill init
39
- ```
40
-
41
- Acknowledge a finding so it stops showing up until the skill's content changes:
42
-
43
- ```
44
- drskill ack near-duplicate docx-report documentation-writer
45
- ```
46
-
47
- Walk the findings one at a time and decide each with one keypress:
48
-
49
- ```
50
- drskill review
51
- ```
52
-
53
- `review` shows each finding with its full evidence and takes single-key actions: `a` acks it, `n` acks it with a note, `f` queues its fix commands for a copy and paste block at the end, `s` skips it, and `q` quits. Acks are written as you go, so quitting midway loses nothing. `review` only runs in a real terminal. When stdin or stdout is not a TTY, or `CI` or `DRSKILL_NO_INTERACTIVE` is set, it prints one line pointing at `scan` and `ack` and exits. `scan` itself never prompts, so a script or an agent calling drskill can never get stuck at a prompt.
54
-
55
- Print the full evidence for one finding, or for a whole check class:
56
-
57
- ```
58
- drskill show fe5b
59
- drskill show injection-egress
60
- ```
61
-
62
- List every harness's effective skill set with token counts:
63
-
64
- ```
65
- drskill list --tokens
66
- ```
67
-
68
- Scan and also print each harness's skill table in one run:
69
-
70
- ```
71
- drskill scan --detailed
72
- ```
73
-
74
- Scope the scan to a single harness and see exactly what that harness sees:
75
-
76
- ```
77
- drskill scan --harness pi
78
- ```
79
-
80
- An unknown harness id is an error that names the valid ids. Harnesses that are detected but load no skills are hidden from the tables by default; a closing line names them, and `--all` shows them.
81
-
82
- Run in CI, where any unacknowledged warning should fail the build:
83
-
84
- ```
85
- drskill scan --ci
86
- ```
87
-
88
- ## Exit codes
89
-
90
- | code | meaning |
91
- |---|---|
92
- | 0 | clean, or every finding is acknowledged |
93
- | 1 | at least one error-level finding is active |
94
- | 2 | only warnings are active, but `--ci` was passed |
95
-
96
- Without `--ci`, warnings alone exit 0. This lets you run `drskill scan` locally without it failing your shell, while still failing CI on the same warnings.
97
-
98
- ## Checks
99
-
100
- | check id | severity | fires when |
101
- |---|---|---|
102
- | `name-shadow` | warning | Two skills share a name in one harness's set and one shadows the other. The message names the winner and the rule that picked it. |
103
- | `double-load` | error | One harness loads the same logical skill twice through two directories. |
104
- | `exact-duplicate` | warning | Two contributors have equal normalized content hashes under different names or paths. |
105
- | `near-duplicate` | warning | Jaccard similarity of MinHash signatures over word shingles is at or above the threshold. The default threshold is 0.85 and can be changed in the ledger. |
106
- | `spec-name-mismatch` | error | Frontmatter `name` does not match the folder name. |
107
- | `spec-missing-description` | error | The description is absent or empty. |
108
- | `spec-description-too-long` | error | The description exceeds 1024 characters. |
109
- | `spec-invalid-frontmatter` | error | The frontmatter does not parse as YAML. |
110
- | `frontmatter-angle-brackets` | warning | Frontmatter values contain angle brackets, which the spec flags as an injection vector. |
111
- | `broken-symlink` | error | A symlink in a skill directory points at nothing. |
112
- | `lockfile-drift` | warning | A skill's content hash does not match its `skills-lock.json` entry. The message attributes the likely cause, e.g. a `gh skill update` or a hand edit, and does not call it corruption. |
113
- | `budget-catalog-tokens` | warning | A harness's total catalog tokens exceed `[budget] catalog_tokens_max`. |
114
- | `budget-body-tokens` | warning | A skill's body tokens exceed `[budget] body_tokens_warn`. |
115
- | `description-overlap` | warning | Two or more descriptions are similar enough that a router could confuse them. The finding names the cluster and the trigger phrases they share. Threshold `description_overlap`. |
116
- | `missing-activation` | warning | A description never states when the skill should trigger, e.g. no "when", "trigger", or "if the user" phrasing. |
117
- | `generic-description` | warning | A description has fewer distinctive words than `generic_min_distinct_tokens`, e.g. "Helps with various tasks." |
118
- | `opposing-imperatives` | warning | Two skills give opposite orders about the same action, e.g. "Always use tabs" against "Never use tabs". Deliberately strict matching, so paraphrased conflicts are not caught. |
119
- | `injection-unicode` | error | Skill text or a bundled file contains bidirectional control characters or zero-width characters. These can hide instructions from a human reviewer. |
120
- | `injection-credential-read` | error | A bundled script references credential paths such as `~/.ssh`, `~/.aws`, or private key files. Reads of `.env` alone downgrade to a warning. |
121
- | `injection-override` | warning | Skill text contains instruction-override phrasing, e.g. "ignore all previous instructions" or "without informing the user". |
122
- | `injection-mandatory-script` | warning | The skill demands that its own bundled script runs as a required first step, e.g. "you must first run scripts/setup.sh". |
123
- | `injection-egress` | warning | A bundled script calls the network, e.g. `curl` or `requests.post`. The finding quotes each call so you can check the destination. |
124
- | `injection-encoded-blob` | warning | Skill text or a bundled file contains a long base64 or hex run that a reviewer cannot read. |
125
- | `injection-remote-fetch` | warning | Skill text tells the agent to fetch remote content and act on it, e.g. `curl` piped to a shell or "download X and follow the instructions". |
126
-
127
- ## The ledger
128
-
129
- `drskill.toml` sits at the root of your repo and should be committed. It holds your budgets, your thresholds, and your decisions. When you run `drskill ack`, it appends an entry like this:
130
-
131
- ```toml
132
- [[ack]]
133
- check = "near-duplicate"
134
- skills = ["docx-report", "documentation-writer"]
135
- fingerprint = "sha256:..."
136
- note = "docx is output format specific; keeping both"
137
- date = 2026-07-19
138
- ```
139
-
140
- A finding's fingerprint is a hash of the check id plus the content of every skill involved. An ack silences a finding only while that fingerprint still matches. If you edit one of the skills named in the ack, its content hash changes, the fingerprint no longer matches, and the finding comes back on the next scan. This is deliberate. An ack means "this exact situation is fine," not "never check this pair again."
141
-
142
- In global mode (`--global`), the ledger lives at `~/.drskill.toml` instead.
143
-
144
- Acks are scope aware. When a finding involves only machine-level skills, e.g. a vendored skill under your home directory that has nothing to do with the current repo, `drskill ack` writes the ack to `~/.drskill.toml` and says so. Every project scan honors acks from both ledgers, so you decide once per machine instead of once per repo. When any project skill is involved, the ack goes to the project's committed `drskill.toml` as before. Two flags override the routing: `--local` forces the project ledger, and `--global-ack` forces the machine ledger.
145
-
146
- ## Reading the report
147
-
148
- Findings print errors first, then warnings. Inside each section the order is: findings you have not seen before, then findings on skills you installed, then findings on harness-vendored skills, which carry a `[system skill]` label. A finding you have not seen carries a `new` tag, and the summary line counts them. The memory behind the `new` tag lives in `~/.drskill/state/`, one small file per project. It only records what the report has shown you; it is not the ledger, and `--json` runs never touch it, so an agent polling drskill does not clear your markers. When a finding affects every detected harness, the harness line collapses to a count, e.g. "all 7 harnesses". Checks that flag description quality report one finding listing every offending skill, so three skills with the same problem are one entry and one ack.
149
-
150
- The `source` column in `list` shows where a skill came from: `skills-lock` for skills named in a project's `skills-lock.json`, `gh-skill` for skills with `gh skill` provenance in their frontmatter, and `linked` for skills that live in or link into a `.agents/skills` store. The `linked` label means an installer arranged the layout; drskill does not guess which one. `unmanaged` means a plain directory with no known manager.
151
-
152
- ## Known limitations
153
-
154
- Comments in `drskill.toml` are lost when `drskill ack` rewrites the file. The file is parsed and re-written as data, and the writer does not carry comments forward. If you rely on comments to explain a budget or a threshold, keep that explanation in a separate note, not inline in the file.
155
-
156
- Claude Code skills bundled inside plugins are not scanned yet. drskill only walks the plain `.claude/skills` directories described in the harness table; it does not look inside installed plugin packages.
157
-
158
- `skills-lock.json` hash verification is self-calibrating. Upstream `npx skills` computes its own content hashes, and drskill cannot always reproduce them exactly. If none of the hashes in a lockfile match what drskill computes, it will not accuse every skill of drift; instead it prints one warning saying the hashes could not be verified against that lockfile. Per-skill drift warnings only appear once drskill has confirmed, by matching at least one hash, that its hashing algorithm agrees with that lockfile's producer.
159
-
160
- Harness rules are verified in two parts, because they have two different jobs. Paths verification covers which directories a harness reads and whether it searches them recursively. Precedence verification covers which copy wins when two skills share a name. Claude Code, Pi, Gemini CLI, Codex, and Cline are verified on both. Cursor is verified on paths only, since its docs do not say which copy wins a collision. Copilot is unverified on both, since its docs do not confirm recursion and the CLI is closed source. About 65 further harnesses are vendored from the `vercel-labs/skills` project and are unverified on both.
161
-
162
- A finding only inherits the uncertainty it actually depends on. Shadowing and double-load findings depend on precedence; every other finding depends only on paths. When a harness in a finding's list is unverified for the part that finding depends on, its name carries a `?` suffix, and the report ends with one legend line explaining it. A finding with no `?` rests entirely on verified rules.
163
-
164
- Token counts are approximate. drskill counts tokens with `tiktoken`'s `o200k_base` encoding, which is a reasonable estimate but will not match every harness's actual tokenizer or catalog rendering exactly.
165
-
166
- The seven injection checks flag surfaces; they do not verify intent. Static analysis cannot prove a skill benign or hostile, so every injection finding quotes the exact lines it judged and leaves the verdict to you. A clean scan is not a security guarantee, and a finding is not an accusation. Bundled files that are binary or larger than 1 MiB are recorded but not content scanned, and the report says so when that happens. A bundled file counts as a script when it has a script extension or a shebang line; everything else is scanned as prose, so the script-only checks (egress, credential reads) do not look inside files disguised as plain text.
167
-
168
- The four description and instruction checks are heuristics. Their thresholds are tuned against real public skill sets to stay quiet on well-written skills, and every finding can be acknowledged, but they will miss paraphrased conflicts and will flag some judgment calls. The thresholds live in `drskill.toml`:
169
-
170
- ```toml
171
- [thresholds]
172
- near_duplicate = 0.85
173
- description_overlap = 0.6
174
- generic_min_distinct_tokens = 2
175
- ```
drskill-0.2.0/README.md DELETED
@@ -1,161 +0,0 @@
1
- ### They Call Me Dr. Skill
2
-
3
- drskill is `brew doctor` for your agent's skill loadout. It looks at every coding agent installed on your machine or configured in your repo, works out exactly which skills each one loads, and checks that set for problems: skills that shadow each other, skills loaded twice, duplicate or near-duplicate skills, skills that break the SKILL.md spec, broken symlinks, drift against your lockfile, and skills that burn too many tokens. Every problem it reports ends in a command: a fix command or a command to acknowledge the problem and move on. drskill only reads your files. It never installs, edits, or deletes a skill, and it makes zero calls to an LLM.
4
-
5
- ## Install
6
-
7
- ```
8
- uv tool install drskill
9
- ```
10
-
11
- ## Quick start
12
-
13
- Run a scan from the root of a project:
14
-
15
- ```
16
- drskill scan
17
- ```
18
-
19
- This detects every coding agent it can find, resolves each one's effective skill set, and prints a report grouped by severity. Each finding names the harnesses it affects and ends in a fix command or an ack command.
20
-
21
- Write a starter ledger file with default budgets and thresholds:
22
-
23
- ```
24
- drskill init
25
- ```
26
-
27
- Acknowledge a finding so it stops showing up until the skill's content changes:
28
-
29
- ```
30
- drskill ack near-duplicate docx-report documentation-writer
31
- ```
32
-
33
- Walk the findings one at a time and decide each with one keypress:
34
-
35
- ```
36
- drskill review
37
- ```
38
-
39
- `review` shows each finding with its full evidence and takes single-key actions: `a` acks it, `n` acks it with a note, `f` queues its fix commands for a copy and paste block at the end, `s` skips it, and `q` quits. Acks are written as you go, so quitting midway loses nothing. `review` only runs in a real terminal. When stdin or stdout is not a TTY, or `CI` or `DRSKILL_NO_INTERACTIVE` is set, it prints one line pointing at `scan` and `ack` and exits. `scan` itself never prompts, so a script or an agent calling drskill can never get stuck at a prompt.
40
-
41
- Print the full evidence for one finding, or for a whole check class:
42
-
43
- ```
44
- drskill show fe5b
45
- drskill show injection-egress
46
- ```
47
-
48
- List every harness's effective skill set with token counts:
49
-
50
- ```
51
- drskill list --tokens
52
- ```
53
-
54
- Scan and also print each harness's skill table in one run:
55
-
56
- ```
57
- drskill scan --detailed
58
- ```
59
-
60
- Scope the scan to a single harness and see exactly what that harness sees:
61
-
62
- ```
63
- drskill scan --harness pi
64
- ```
65
-
66
- An unknown harness id is an error that names the valid ids. Harnesses that are detected but load no skills are hidden from the tables by default; a closing line names them, and `--all` shows them.
67
-
68
- Run in CI, where any unacknowledged warning should fail the build:
69
-
70
- ```
71
- drskill scan --ci
72
- ```
73
-
74
- ## Exit codes
75
-
76
- | code | meaning |
77
- |---|---|
78
- | 0 | clean, or every finding is acknowledged |
79
- | 1 | at least one error-level finding is active |
80
- | 2 | only warnings are active, but `--ci` was passed |
81
-
82
- Without `--ci`, warnings alone exit 0. This lets you run `drskill scan` locally without it failing your shell, while still failing CI on the same warnings.
83
-
84
- ## Checks
85
-
86
- | check id | severity | fires when |
87
- |---|---|---|
88
- | `name-shadow` | warning | Two skills share a name in one harness's set and one shadows the other. The message names the winner and the rule that picked it. |
89
- | `double-load` | error | One harness loads the same logical skill twice through two directories. |
90
- | `exact-duplicate` | warning | Two contributors have equal normalized content hashes under different names or paths. |
91
- | `near-duplicate` | warning | Jaccard similarity of MinHash signatures over word shingles is at or above the threshold. The default threshold is 0.85 and can be changed in the ledger. |
92
- | `spec-name-mismatch` | error | Frontmatter `name` does not match the folder name. |
93
- | `spec-missing-description` | error | The description is absent or empty. |
94
- | `spec-description-too-long` | error | The description exceeds 1024 characters. |
95
- | `spec-invalid-frontmatter` | error | The frontmatter does not parse as YAML. |
96
- | `frontmatter-angle-brackets` | warning | Frontmatter values contain angle brackets, which the spec flags as an injection vector. |
97
- | `broken-symlink` | error | A symlink in a skill directory points at nothing. |
98
- | `lockfile-drift` | warning | A skill's content hash does not match its `skills-lock.json` entry. The message attributes the likely cause, e.g. a `gh skill update` or a hand edit, and does not call it corruption. |
99
- | `budget-catalog-tokens` | warning | A harness's total catalog tokens exceed `[budget] catalog_tokens_max`. |
100
- | `budget-body-tokens` | warning | A skill's body tokens exceed `[budget] body_tokens_warn`. |
101
- | `description-overlap` | warning | Two or more descriptions are similar enough that a router could confuse them. The finding names the cluster and the trigger phrases they share. Threshold `description_overlap`. |
102
- | `missing-activation` | warning | A description never states when the skill should trigger, e.g. no "when", "trigger", or "if the user" phrasing. |
103
- | `generic-description` | warning | A description has fewer distinctive words than `generic_min_distinct_tokens`, e.g. "Helps with various tasks." |
104
- | `opposing-imperatives` | warning | Two skills give opposite orders about the same action, e.g. "Always use tabs" against "Never use tabs". Deliberately strict matching, so paraphrased conflicts are not caught. |
105
- | `injection-unicode` | error | Skill text or a bundled file contains bidirectional control characters or zero-width characters. These can hide instructions from a human reviewer. |
106
- | `injection-credential-read` | error | A bundled script references credential paths such as `~/.ssh`, `~/.aws`, or private key files. Reads of `.env` alone downgrade to a warning. |
107
- | `injection-override` | warning | Skill text contains instruction-override phrasing, e.g. "ignore all previous instructions" or "without informing the user". |
108
- | `injection-mandatory-script` | warning | The skill demands that its own bundled script runs as a required first step, e.g. "you must first run scripts/setup.sh". |
109
- | `injection-egress` | warning | A bundled script calls the network, e.g. `curl` or `requests.post`. The finding quotes each call so you can check the destination. |
110
- | `injection-encoded-blob` | warning | Skill text or a bundled file contains a long base64 or hex run that a reviewer cannot read. |
111
- | `injection-remote-fetch` | warning | Skill text tells the agent to fetch remote content and act on it, e.g. `curl` piped to a shell or "download X and follow the instructions". |
112
-
113
- ## The ledger
114
-
115
- `drskill.toml` sits at the root of your repo and should be committed. It holds your budgets, your thresholds, and your decisions. When you run `drskill ack`, it appends an entry like this:
116
-
117
- ```toml
118
- [[ack]]
119
- check = "near-duplicate"
120
- skills = ["docx-report", "documentation-writer"]
121
- fingerprint = "sha256:..."
122
- note = "docx is output format specific; keeping both"
123
- date = 2026-07-19
124
- ```
125
-
126
- A finding's fingerprint is a hash of the check id plus the content of every skill involved. An ack silences a finding only while that fingerprint still matches. If you edit one of the skills named in the ack, its content hash changes, the fingerprint no longer matches, and the finding comes back on the next scan. This is deliberate. An ack means "this exact situation is fine," not "never check this pair again."
127
-
128
- In global mode (`--global`), the ledger lives at `~/.drskill.toml` instead.
129
-
130
- Acks are scope aware. When a finding involves only machine-level skills, e.g. a vendored skill under your home directory that has nothing to do with the current repo, `drskill ack` writes the ack to `~/.drskill.toml` and says so. Every project scan honors acks from both ledgers, so you decide once per machine instead of once per repo. When any project skill is involved, the ack goes to the project's committed `drskill.toml` as before. Two flags override the routing: `--local` forces the project ledger, and `--global-ack` forces the machine ledger.
131
-
132
- ## Reading the report
133
-
134
- Findings print errors first, then warnings. Inside each section the order is: findings you have not seen before, then findings on skills you installed, then findings on harness-vendored skills, which carry a `[system skill]` label. A finding you have not seen carries a `new` tag, and the summary line counts them. The memory behind the `new` tag lives in `~/.drskill/state/`, one small file per project. It only records what the report has shown you; it is not the ledger, and `--json` runs never touch it, so an agent polling drskill does not clear your markers. When a finding affects every detected harness, the harness line collapses to a count, e.g. "all 7 harnesses". Checks that flag description quality report one finding listing every offending skill, so three skills with the same problem are one entry and one ack.
135
-
136
- The `source` column in `list` shows where a skill came from: `skills-lock` for skills named in a project's `skills-lock.json`, `gh-skill` for skills with `gh skill` provenance in their frontmatter, and `linked` for skills that live in or link into a `.agents/skills` store. The `linked` label means an installer arranged the layout; drskill does not guess which one. `unmanaged` means a plain directory with no known manager.
137
-
138
- ## Known limitations
139
-
140
- Comments in `drskill.toml` are lost when `drskill ack` rewrites the file. The file is parsed and re-written as data, and the writer does not carry comments forward. If you rely on comments to explain a budget or a threshold, keep that explanation in a separate note, not inline in the file.
141
-
142
- Claude Code skills bundled inside plugins are not scanned yet. drskill only walks the plain `.claude/skills` directories described in the harness table; it does not look inside installed plugin packages.
143
-
144
- `skills-lock.json` hash verification is self-calibrating. Upstream `npx skills` computes its own content hashes, and drskill cannot always reproduce them exactly. If none of the hashes in a lockfile match what drskill computes, it will not accuse every skill of drift; instead it prints one warning saying the hashes could not be verified against that lockfile. Per-skill drift warnings only appear once drskill has confirmed, by matching at least one hash, that its hashing algorithm agrees with that lockfile's producer.
145
-
146
- Harness rules are verified in two parts, because they have two different jobs. Paths verification covers which directories a harness reads and whether it searches them recursively. Precedence verification covers which copy wins when two skills share a name. Claude Code, Pi, Gemini CLI, Codex, and Cline are verified on both. Cursor is verified on paths only, since its docs do not say which copy wins a collision. Copilot is unverified on both, since its docs do not confirm recursion and the CLI is closed source. About 65 further harnesses are vendored from the `vercel-labs/skills` project and are unverified on both.
147
-
148
- A finding only inherits the uncertainty it actually depends on. Shadowing and double-load findings depend on precedence; every other finding depends only on paths. When a harness in a finding's list is unverified for the part that finding depends on, its name carries a `?` suffix, and the report ends with one legend line explaining it. A finding with no `?` rests entirely on verified rules.
149
-
150
- Token counts are approximate. drskill counts tokens with `tiktoken`'s `o200k_base` encoding, which is a reasonable estimate but will not match every harness's actual tokenizer or catalog rendering exactly.
151
-
152
- The seven injection checks flag surfaces; they do not verify intent. Static analysis cannot prove a skill benign or hostile, so every injection finding quotes the exact lines it judged and leaves the verdict to you. A clean scan is not a security guarantee, and a finding is not an accusation. Bundled files that are binary or larger than 1 MiB are recorded but not content scanned, and the report says so when that happens. A bundled file counts as a script when it has a script extension or a shebang line; everything else is scanned as prose, so the script-only checks (egress, credential reads) do not look inside files disguised as plain text.
153
-
154
- The four description and instruction checks are heuristics. Their thresholds are tuned against real public skill sets to stay quiet on well-written skills, and every finding can be acknowledged, but they will miss paraphrased conflicts and will flag some judgment calls. The thresholds live in `drskill.toml`:
155
-
156
- ```toml
157
- [thresholds]
158
- near_duplicate = 0.85
159
- description_overlap = 0.6
160
- generic_min_distinct_tokens = 2
161
- ```