docs(skill): warn authors against raw URLs in field descriptions

Pairs with the config-sheet wrap fix in d616935. Even though the
Configuration sheet now renders raw URLs correctly, markdown link
syntax reads cleaner in the form — the visible text is the label,
not the URL. Teaching this in SKILL.md prevents the scaffolding
skill from generating schemas that look worse than they could.

Additions to SKILL.md:
- New "Writing good descriptions" subsection under Config Schema
  Design. Good/bad examples side by side; rule of thumb to wrap
  long unbreakable strings (URLs, paths) in markdown links or
  inline code.
- New item in the Common Pitfalls checklist: "No raw URLs in
  field descriptions."

Bundle rebuilt, catalog.json regenerated. 24/24 Python tests
still pass; Python validator treats descriptions as opaque strings
so no validator changes needed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alan Wizemann
2026-04-23 21:43:45 +02:00
parent d616935296
commit 5e207f760d
3 changed files with 19 additions and 2 deletions
+2 -2
View File
@@ -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": {