fix(skill-author): resolve skill-audit findings

- script: new-skill.sh now exits 0 when target already exists (idempotent
  retry-safe) instead of exit 1; --help updated to reflect narrowed error cases
- test: updated bats test to assert success and "nothing to do" output
- body: removed speculative "Extract the skill from a real task" advice
  (human-targeted, not agent-actionable)
- formatting: converted H4 headings in Step 2 to bold text (H2/H3 two-tier model)
- provenance: removed orphan agentskills-llms-txt entry from references/sources.md;
  added discovery-only comment

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-06-26 21:24:11 +00:00
parent 99e64d67fc
commit 08abe9920a
4 changed files with 14 additions and 19 deletions

View File

@@ -46,7 +46,6 @@ Run `/grill-me` on the skill's design and research the target domain first.
Share those outputs in this conversation: grill context, research docs, examples, constraints.
Design for one coherent user intent — skills too narrow force multiple loads per task; too broad are hard to activate precisely.
Extract the skill from a real task you've done — a skill refined from real execution outperforms one written speculatively.
**Before touching the filesystem, verify you have:**
- [ ] A clear purpose — what specific task will this skill handle?
@@ -79,7 +78,7 @@ If the destination is inside a plugin directory (path contains a `plugin.json`),
Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeholder.
#### Frontmatter
**Frontmatter**
**`name`** — already set by the scaffold script. Must exactly match the directory name. Format: 1–64 characters, lowercase letters/numbers/hyphens only, no leading, trailing, or consecutive hyphens (`--`).
@@ -97,7 +96,7 @@ Open `<destination-dir>/<skill-name>/SKILL.md`. Replace every `FILL IN:` placeho
- `metadata` — key-value map; use `author`, `version`, `category`
- `allowed-tools` — space-separated pre-approved tools; reduces permission prompts (experimental — support varies by client)
#### Body — include only what the agent lacks
**Body — include only what the agent lacks**
Rename the placeholder section heading to one that fits the skill's structure — `## Step 1`, `## Workflow`, `## Instructions`, etc.
@@ -115,7 +114,7 @@ Ask of every sentence: "Would the agent get this wrong without it?" Cut anything
- Steps the agent handles independently — over-specifying leads agents to follow unproductive paths
- Restatements of the description — it's already in context; repeating it wastes the token budget
#### Patterns
**Patterns**
**Gotchas** — highest value; place near the top:
````markdown
@@ -159,7 +158,7 @@ Output format:
````
For longer templates, place in `assets/<name>.md` and reference conditionally.
#### Size budget
**Size budget**
Keep `SKILL.md` under 500 lines; 5,000 tokens is the recommended body budget. When approaching the limit:
- Move reference material to `references/<topic>.md` and load it conditionally