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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user