Defame1297
dac9cad912
skill-audit loaded roughly 4,268 words of rubric on every run, most of it criteria for findings a clean skill never triggers. The auditing guidance moves into finding-criteria.md, read only when a finding is actually raised, cutting a clean audit to about 999 words. The named-skill exemption is replaced with properties, so the rubric stops carrying a list that ages the moment a skill is renamed. apm-workflow's `type:` trap sat in one flow while biting several, so it is promoted to a common gate reachable from all of them; its claim to be self-contained was untrue once it started routing to apm-install. skill-author's contract had drifted from body-discipline.md and is realigned, and agent-audit's field inventory is brought in line with the same split.
2.4 KiB
2.4 KiB
source_keys
| source_keys | ||
|---|---|---|
|
Formatting and Scripts Reference
Upstream source: agentskills.io — specification (body content), using-scripts (designing scripts for agentic use).
Read this when judging the formatting and scripts dimensions. Both are checklists of static criteria that never vary by skill, which is exactly why they live here rather than in the body.
Formatting
- Heading levels are consistent: H2 for main sections, H3 for subsections. A body that jumps from H2 to H4, or opens on H3, reads as a fragment of a larger document.
- Code blocks carry a language tag wherever one applies —
bash,markdown,python,yaml,text. An untagged block loses syntax highlighting and, more importantly, loses the signal of what the agent is meant to do with it. - Whitespace is consistent: a blank line between sections, one list-indentation style throughout.
- No broken relative paths in file references. Every
references/…,scripts/…andassets/…path named in the body resolves against the skill directory.
Scripts
A script in a skill is run by an agent with no terminal and no human to answer it. The criteria follow from that:
- No interactive TTY prompts — no
read, noinput(), noreadline. A script that blocks on a prompt hangs the run with no diagnostic.validate.shdetects the common forms and reports them under Structure; the judgment call is any prompt it cannot pattern-match. What counts is where stdin comes from, not the wordread: areadfed by a here-string, a here-doc, a pipe, or a redirect from a file never touches a terminal and is not a finding.validate.shexcludes those forms, so do not rewrite a workingread -r A B <<< "$line"into parameter expansion to satisfy this rule. --helpis exposed and gives concise usage.- Data to stdout, diagnostics to stderr. A caller piping the script has to be able to separate the result from the commentary.
- Idempotent — "create if not exists" rather than "create", so a re-run after a partial failure is safe.
- Meaningful exit codes, documented in
--help. An agent branches on the exit code; an undocumented one is a coin flip. --dry-runpresent for destructive operations.
The FAIL and SUGGESTION criteria for this dimension live in references/finding-criteria.md,
which Step 3 loads on every run.