skillz-that-grillzBLOCK

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: skillz
description: >
  Add, improve, audit, wedge, or autoimprove a skill. Improve and audit also accept a
  sub-agent definition. The result runs predictably on Claude Code, Codex, OMP, and other Agent Skills hosts.
  Use for /skillz <add|improve|audit|wedge|autoimprove>, "improve this skill",
  "autoimprove this skill",
  "optimize this skill", "tighten this skill",
  "audit this agent", "new skill for X", "skill not triggering", "fix
  trigger rate", "wedge this", "turn this repeated work into a CLI", or
  "what in this skill should be a CLI". Do NOT use for
  CLAUDE.md or system-prompt edits, or for code changes that a cheese
  pipeline skill owns.
disable-model-invocation: true
argument-hint: "<add|improve|audit|wedge|autoimprove> [<path>|<name>]"
license: MIT
metadata:
  author: paulnsorensen
  dispatches-agents: audit and improve, when the host offers sub-agents
---

# skillz

Add, improve, audit, wedge, and autoimprove skills.
Improve and audit also accept agent definitions.
The product is a **predictable** definition: the same process on every run and on every harness.
Every lens asks one question of each line: *does this make the run more predictable, or is it sediment?*

The mode is the first word after the skill name.
The Aliases column lists the names that select the same mode.
Require a target for each mode.
Ask for the mode when it is missing.
Ask for a target when the mode requires one.

## Modes

| Mode | Aliases | Target | Analytics | Writes | Product |
|---|---|---|---|---|---|
| `add <name>` | none | a new skill name | no | creates `skills/<name>/` | a registered skill that passes the rubric |
| `improve <path>` | `optimize`, `tighten` | a `SKILL.md` or agent file | yes, unless it reuses a current audit | the analytics cache; the target after approval | approved fixes + residual findings |
| `audit <path>` | none | a `SKILL.md` or agent file | yes | the analytics cache only; never the target | calibrated report |
| `wedge <path>` | none | a `SKILL.md` | no | the target skill: each selected CLI, its delivery files, its call site, and any dependency write | an offload brief, then one CLI per selected candidate, each in its own directory when wedged, or with a stated reason |
| `autoimprove <path>` | `experiment` | a skill directory; no contract or manifest | cases that the user approves; agent-drafted session cases when analytics exists | isolated run directory | a holdout gate verdict and a private candidate patch |

`audit` never modifies the target. The Usage ceremony of `audit` and `improve` runs `ingest.py`, which creates or refreshes the analytics cache.
`references/analytics-ceremony.md` has the details. Skip Usage and the raw-log fallback write no cache.

For `autoimprove`, read `references/experiments.md`. Follow its workflow, not the shared audit protocol.
The agent drafts the cases. The user needs no contract and no case manifest.
Run `scripts/skillz-experiment.pyz run`, answer each coded stop, and then run `export`.
Ask at most three questions: harness and model, case approval, and budget approval.
When the user selects the `claude` adapter or a custom command check, also read `references/experiment-harness.md`.
Use the installed `scripts/skillz-experiment.pyz`. Do not require a source checkout.

## Shared protocol

### 1. Read and classify

Read the target. Read a linked reference only when its stated trigger matches the run.
A full-package audit may explicitly read every file in the target package.
For a skill directory, run `python3 <this-skill-directory>/scripts/skillz-experiment.pyz audit-facts <skill-directory>` before applying the rubric.
Also run `python3 -I <this-skill-directory>/scripts/inspect-skill.pyz <target>` for the prose facts.
Use both JSON outputs as objective package facts, not a fitness score. An agent file has no package, so skip `audit-facts`.
Read `references/experiments.md § Audit facts contract` for the check ids and statuses.
Report a helper error without treating it as a successful audit.
Classify it as **agent** (`tools:` / `disallowedTools:` or an `agents/registry.yaml` entry) or **skill** (`name:` + `description:`).
For a skill, run `git ls-files -z -co --exclude-standard <skill-dir> | LC_ALL=C sort -z | xargs -0 git hash-object | git hash-object --stdin`.
Its output is the content id. It covers every package file, so a sidecar or reference edit changes it.
For an agent file, run `git hash-object <target>`. Its output is the content id.
When a command fails, the content id is `unavailable`.
Report the body size as `~N tok` against the 5k budget.
For a skill, copy it from the `body.token-estimate` check. For an agent file, count bytes/4 after the frontmatter block.
List the deploy targets the definition reaches (`references/harness-layout.md § Layout`).

### 2. Rubric

Score each lens.
Each row names the principle, the failure mode it catches, and a checkable test.
Read `references/anti-patterns.md` when a finding needs the expanded form.

| Lens | Principle → catches | Check |
|---|---|---|
| **Predictability** | Fixed protocol with checkable completion → «premature completion» | Every step ends on a done-condition an agent can verify. |
| **Invocation** | `description` = trigger conditions, front-loaded, third person → «workflow summary», «summary description» | Trigger phrases + "Do NOT use for"; no internal workflow; skills take length from `description.length`, agent files stay at ≤1024 chars by hand; first sentence carries the trigger. `references/description-optimization.md`. |
| **Portability** | Spec-core frontmatter plus additive Claude fields; user-only policy on every host → «Claude-only assumption», «sidecar missing», «`$ARGUMENTS` dependence» | Cite failed `audit-facts` checks for keys, sidecar pairing, and argument, skill-directory, or file-mention syntax. Judge by hand: args are parsed from the text after the skill name; skills are cross-referenced by `/name`; dispatch and GitHub ops name the contract 

BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

declared (9 observation(s))

Network

declared (1 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (25)

HOME_DENY = (".ssh", ".gnupg", ".aws", ".config", ".docker", ".kube", ".netrc", ".claude.json", ".bashrc", ".zshrc", ".zshenv",

".profile", ".bash_profile", ".bash_history", ".zsh_history", ".git-credentials", ".npmrc", ".pypirc",

.claude/skills/python-authoring

.claude/skills/release

.claude/skills/skillz-self-update

print(f"note: split quoted argument {token!r} into {pieces!r}", file=sys.stderr)

.coderabbit.yaml

.markdownlint.jsonc

.yamlfmt

.yamllint.yml

exec(match[0], scope)  # noqa: S102 - the grader source from the repository manifest

exec(compile(LAUNCHER_SOURCE, "launcher", "exec"), namespace)

"import hashlib, json, pathlib, re\ndef read(name):\n    try:\n        return pathlib.Path(name).read_text()\n    except OSError:\n        return None\nout = {p.relative_to('output').as_posix(): p.rea

names = (".bashrc", ".zshrc", ".zshenv", ".profile", ".bash_profile", ".bash_history", ".zsh_history", ".git-credentials",

if name.endswith("json") or name == ".netrc":

assert (hit["status"], hit["line"], hit["path"]) == ("pass", 7, "../../README.md")

link.symlink_to("../../.agents/skills/demo")

link.symlink_to("../../.agents/skills/missing")

'project = "../.."\nrepo = "o/n"\n\n[[target]]\nname = "alpha"\nentry = "alpha:main"\nsource = "../../alpha"\n\n'

+ '[[target]]\nname = "beta"\nentry = "beta:main"\nsource = "../../beta"\n')

assert "http://localhost:" in prompt and "http://127.0.0.1:" in prompt

UNROUTABLE = "http://127.0.0.1:9"

yield f"http://127.0.0.1:{server.server_port}", serve_root, handler_cls

"skill-unicode-lookalike": broken(skill="еcho-skill"),

@pytest.mark.parametrize("name", ["café", "\U0001f9c0 brie", "a:b:c", "line\nbreak", "x" * 10_000, " ", "RTL",

Gates applied: no_behavioural_pass.