coding-agent-skillsSAFE

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: analyze-skill-cost
description: "Audit an agent skill for cost and efficiency: token footprint, tool calls, deterministic work left to prose, subagent overhead, runtime adapters, model, and allowed-tools. Read-only findings report. Use it when asked what a skill costs, why it is slow or expensive, or to check one before shipping it."
argument-hint: "<SkillName>"
allowed-tools: ["Bash(python -B \"${CLAUDE_SKILL_DIR}/scripts/*)", "PowerShell(python -B \"${CLAUDE_SKILL_DIR}/scripts/*)", "Read", "Grep"]
---

Audit a named agent skill for cost and efficiency regressions and render a bucketed findings report. Read-only — no edits, no prompts.

The measurements are commands of `skill_inventory.py`, run exactly as shown. Each prints one fact per line, with paths in forward-slash form; a missing or unreadable input prints `FAILED <reason>` as its last line; stop and report it. Do not re-measure, re-count, or write your own code for anything a command reports. Your job is the judgment the commands cannot make.

## Step 0 — Parse `$ARGUMENTS`

Trim leading/trailing whitespace. If empty, print `usage: analyze-skill-cost <SkillName>` and stop. Otherwise `SKILL_NAME=$ARGUMENTS`. No flags.

## Step 1 — Locate the skill

```bash
python -B "${CLAUDE_SKILL_DIR}/scripts/skill_inventory.py" locate "<SKILL_NAME>"
```

It searches `{{HOME}}/.claude/skills/`, the current repository's `.agents/skills/` and `.claude/skills/`, and, in a skill source tree, `skills/` (`SCOPE source`, preferred over the deployed copy).

- `REPO <path>` or `REPO none`: the repository searched; nothing to do.
- `SKILL_FILE <path>`, `SKILL_DIR <path>`, `SCOPE <scope>`: continue with these.
- `NOT_FOUND <name>` followed by `AVAILABLE <scope> <name>` lines: stop with `skill '<SKILL_NAME>' not found. Available skills: <user: ...> / <project: ...>`.
- `AMBIGUOUS <scope> <path>` lines: stop with `ambiguous skill name '<SKILL_NAME>' — found at: <paths>. Rename one or delete the duplicate.`

## Step 2 — Inventory and token estimate

```bash
python -B "${CLAUDE_SKILL_DIR}/scripts/skill_inventory.py" inventory "<SKILL_DIR>"
```

`FILE` lines list every file by category; a `doc` file is Markdown other than the main `SKILL.md`. `TOTAL` lines fill the report's Scope, and so do `DECLARED <kind> <name>` lines, or `DECLARED_UNREADABLE <path>` when the skill's metadata is not valid JSON. `NO_MAIN` means the folder lost its `SKILL.md`: stop and report it. Step 4 judges the rest.

## Step 3 — Read what the judgment needs

Read the main body and every `doc` file in full; they are what the audit judges. Read a helper script only when a finding depends on it, for example to check whether the body has the agent redo logic the script already implements. Helpers that run through a shell do not load into context: report their size as reference, not as context cost.

## Step 4 — Token footprint

Judge content, not size: a long body whose every section earns its space passes, and a short one full of duplicated prose does not.

- **MUST FIX** — the body contains duplicated code blocks (`DUPLICATE_BLOCK`), prose that restates another step's instruction (such as "Important" bullets repeating step bodies), or trimmable example output. Documentation the agent never acts on, such as safety guarantees the scripts enforce, a glossary of self-labelled output, or a procedure for an action the skill never takes, counts as restatement: recommend moving it to the user documentation.
- **SUGGESTION** — a `doc` file whose content the body copies inline instead of pointing at it. Recommend an instruction to read the file.
- **SUGGESTION** — the structure checks from Anthropic's skill authoring best practices: `BODY_OVER_500_LINES` (split the body into reference files), `DOC_NO_TOC` (add a table of contents; skip a template the agent copies whole), and `NESTED_REFERENCE` (link that file from `SKILL.md`, since references should be one level deep).
- **SUGGESTION** — each `OUTSIDE_READ` file: it costs a turn and its tokens on every run. Recommend keeping only the rules the skill needs in the skill; runtime guidance such as a tool mapping belongs in the runtime adapters. A `DECLARED` dependency the Markdown never names is not a per-run cost.
- **MUST FIX** — each `OUTSIDE_MISSING`: the skill names a file outside its folder that does not exist, so that read fails on every run. Recommend correcting the path or the dependency.
- **SUGGESTION** — each `INLINED_HELPER`. Recommend invoking the script instead of copying it.

## Step 5 — Tool-call efficiency

Pass the main file followed by every `doc` path:

```bash
python -B "${CLAUDE_SKILL_DIR}/scripts/skill_inventory.py" scan "<SKILL_FILE>" "<doc path>"
```

Each `CUE <file> <line> <cue> <text>` is a candidate, not a finding. Read it in context and keep only real findings, anchored as `file:line`. Frontmatter is skipped, and only `wide-glob`, `generated-code`, and `shell-file-command` apply inside fenced blocks.

| Pattern | Cue | Severity | Recommendation |
|---|---|---|---|
| Multiple shell steps described sequentially with no data dependency | — | SUGGESTION | "Issue these in a single assistant turn as parallel tool calls" |
| "Read <file> and then search it for X" | `read-then-search` | SUGGESTION | "Search directly — avoids loading the full file into context" |
| Loop over files with a per-file read | `loop` | SUGGESTION | "Batch with one multi-file search (`-l`, or `-A`/`-B` context)" |
| Search over wide globs (`**/*.cs`, `**/*`) with no `head_limit` | `wide-glob` | MUST FIX | "Add `head_limit` — unbounded output on large repos wastes tokens" |
| `cat`/`head`/`tail`/`find`/`grep`/`rg` in step descriptions rather than scripts | `shell-file-command` | SUGGESTION | "Use the runtime's first-class file/search tools instead of shell calls" |
| The same command run once per item | `per-item-command` | SUGGESTION | "Let the command take several items, so one call covers the batch" |
| Script output shown to the user as-is or ve

SAFEgrade B · trust 85/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

declared (5 observation(s))

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (23)

print(f"OUTCOME {run_host(args.run, args.token, services or Services())}")

export-retention.docx

self.assertIn("+    return eval('+'.join(items))\n", Path(request["diff_path"]).read_text(encoding="utf-8"))

return hashlib.sha1(b"blob %d\0" % len(data) + data, usedforsecurity=False).hexdigest()

UTIL_BLOB = hashlib.sha1(b"blob %d\0" % len(UTIL) + UTIL, usedforsecurity=False).hexdigest()

return hashlib.sha1(b"blob %d\0" % len(data) + data, usedforsecurity=False).hexdigest()

pointer = "Read and follow `../../../.claude/skills/alpha/SKILL.md` as the authoritative workflow.\n"

pointer = "Read and follow `../../../.claude/skills/beta/SKILL.md` as the authoritative workflow.\n"

write(skill / "docs" / "guide.md", "Also `../../shared.md` and `${CLAUDE_SKILL_DIR}/../shared.md`.\n")

"OUTSIDE_READ docs/guide.md:1 9 3 ../../shared.md",

f"Read and follow `../../../.claude/skills/{skill_name}/SKILL.md`"

return sha, base64.b64decode(blob["content"])

given = {bytes.fromhex(call["document"]) for call in stub.calls()}

configuration = base64.b64decode(content).decode("utf-8")

files = {SKILL: "---\ntools: Read\n---\nApply `docs/rules.md`.\n", "docs/rules.md": "Rules\n"}

original = f"Before\r\n\r\n{START_MARKER}\r\nold\r\n{END_MARKER}\r\nAfter — café\r\n".encode()

path.write_bytes('---\r\nname: "crlf"\r\ndescription: >-\r\n  one\r\n  two\r\n---\r\n'.encode())

`scripts/mcp_handshake.py` starts stdio and `local` servers only and skips remote transports, which would need network access and often credentials. It starts each server as a client does: a `command`

way. Do not read it by default. Read it only when your instructions require judging a caller,

says what the author intends, not what the code does. Read it only when your instructions

Output contract (this replaces any output format in your instructions):

way. Do not read it by default. Read it only when your instructions require judging a caller,

says what the author intends, not what the code does. Read it only when your instructions

Gates applied: no_behavioural_pass.