diff --git a/templates/awizemann/template-author/staging/skills/scarf-template-author/SKILL.md b/templates/awizemann/template-author/staging/skills/scarf-template-author/SKILL.md
index 455b33f..1376b09 100644
--- a/templates/awizemann/template-author/staging/skills/scarf-template-author/SKILL.md
+++ b/templates/awizemann/template-author/staging/skills/scarf-template-author/SKILL.md
@@ -202,6 +202,22 @@ Note: `contents.config` is the **count of schema fields**, not a boolean. In the
 
 Every field takes `key` (required), `label` (required), `description` (optional — markdown), `required` (bool), `default` (optional; type matches the field type).
 
+### Writing good descriptions
+
+Descriptions render inline with markdown support (bold, italic, code, links). Keep them short — a single line or two is ideal.
+
+**Always use markdown link syntax for URLs**, never bare `https://…` — the Configuration sheet's inline text renderer doesn't word-break mid-URL, so a raw URL in a description will force that whole description's width to the URL's character length. Older Scarf versions clipped the sheet in that case; current versions wrap correctly, but the visible text is still cleaner with named links.
+
+```json
+// ✓ Good — short label, URL in the href
+"description": "Token with `repo` scope. Get one [from the GitHub tokens page](https://github.com/settings/tokens)."
+
+// ✗ Bad — raw URL bloats the visible text
+"description": "Token with `repo` scope. Get one at https://github.com/settings/tokens"
+```
+
+Same rule for long file paths, API endpoints, or any other unbreakable token — wrap them in inline code (backticks) if they have to appear verbatim, and prefer markdown links otherwise.
+
 ### Hard rules
 
 - **Secret fields MUST NOT have a `default`.** The validator rejects the manifest if they do — a default makes no sense because the Keychain entry doesn't exist yet at install time.
@@ -380,6 +396,7 @@ Things to check before declaring the scaffold done:
 - [ ] Every webview widget has an https URL that renders something meaningful even pre-first-run (Scarf homepage is a decent placeholder).
 - [ ] `dashboard.json` has `version: 1` at the top.
 - [ ] `AGENTS.md` documents every config field, every updated widget, and the cron behaviour — the user relies on it as the source of truth when things drift.
+- [ ] **No raw URLs in field descriptions.** Use `[link text](https://…)` markdown syntax instead — raw URLs read as long unbreakable tokens in the Configuration sheet. Same rule for long paths and other unbreakable strings; wrap in `` ` `` if they must appear verbatim.
 
 ## Reference — source of truth files
 
diff --git a/templates/awizemann/template-author/template-author.scarftemplate b/templates/awizemann/template-author/template-author.scarftemplate
index 5957140..b63d1b0 100644
Binary files a/templates/awizemann/template-author/template-author.scarftemplate and b/templates/awizemann/template-author/template-author.scarftemplate differ
diff --git a/templates/catalog.json b/templates/catalog.json
index f303b5d..8004eff 100644
--- a/templates/catalog.json
+++ b/templates/catalog.json
@@ -69,8 +69,8 @@
         "name": "Alan Wizemann",
         "url": "https://github.com/awizemann"
       },
-      "bundleSha256": "670b2e07ad9bb327c11fa64db1beacf86614a3d388de6fe6e2a19ac957e1346b",
-      "bundleSize": 13889,
+      "bundleSha256": "bebc30551dc92717da96608bbdf448c5d7c47bdb66807037b139a242ef8c3b74",
+      "bundleSize": 14423,
       "category": "developer-tools",
       "config": null,
       "contents": {