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>

plugins/kyberforge/skills/skill-author/SKILL.md

@@ -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

plugins/kyberforge/skills/skill-author/references/sources.md

@@ -1,5 +1,7 @@
 # Sources
 
+<!-- agentskills.io/llms.txt was used for initial source discovery and is not listed below; it contributed no skill file content directly. -->
+
 ## agentskills-home
 
 - **URL:** https://agentskills.io/home.md
@@ -49,9 +51,3 @@
 - **Contributing files:** SKILL.md
 - **Status:** `extracted`
 
-## agentskills-llms-txt
-
-- **URL:** https://agentskills.io/llms.txt
-- **Description:** Documentation index used for source discovery — lists all available pages with URLs
-- **Contributing files:** (none — used for discovery only)
-- **Status:** `extracted`

plugins/kyberforge/skills/skill-author/scripts/new-skill.sh

@@ -20,8 +20,8 @@ Output:
   Creates <destination-dir>/<skill-name>/ with annotated templates ready to fill in.
 
 Exit codes:
-  0  Scaffold created successfully
-  1  Invalid arguments or destination already exists
+  0  Scaffold created successfully, or destination already exists (no-op)
+  1  Invalid arguments, missing destination parent, or templates not found
 EOF
 }
 
@@ -63,11 +63,10 @@ fi
 
 TARGET="$DEST_DIR/$SKILL_NAME"
 
-# Refuse to overwrite existing directory
+# Destination already exists — treat as a no-op so retries are safe
 if [[ -d "$TARGET" ]]; then
-  echo "Error: '$TARGET' already exists." >&2
-  echo "       Remove it first or choose a different name." >&2
-  exit 1
+  echo "Scaffold already exists at '$TARGET' — nothing to do." >&2
+  exit 0
 fi
 
 # Copy templates to destination

plugins/kyberforge/skills/skill-author/tests/new-skill.bats

@@ -111,8 +111,9 @@ teardown() {
     assert_failure
 }
 
-@test "fails when target already exists" {
+@test "exits 0 when target already exists (no-op)" {
     mkdir -p "$DEST/my-tool"
     run bash "$SCRIPT" my-tool "$DEST"
-    assert_failure
+    assert_success
+    assert_output --partial "nothing to do"
 }