Skills fail to load: argument-hint must be a string

[jogoertzen-stantec]

Skills fail to load: argument-hint must be a string

Version: understand-anything 2.8.0
Where: skills/*/SKILL.md frontmatter

Summary

6 of the 8 skills fail to load in strict skill loaders (reproduced in GitHub Copilot CLI, but it affects any loader that validates the field type). The loader reports:

The following skills failed to load:
✖ skills/understand-chat/SKILL.md: argument-hint must be a string
✖ skills/understand-dashboard/SKILL.md: argument-hint must be a string
✖ skills/understand-domain/SKILL.md: argument-hint must be a string
✖ skills/understand-explain/SKILL.md: argument-hint must be a string
✖ skills/understand-knowledge/SKILL.md: argument-hint must be a string
✖ skills/understand/SKILL.md: argument-hint must be a string

Root cause

In YAML, argument-hint: [query] is a flow sequence — it parses to the list ["query"], not the string "[query]". The intended square brackets are literal "optional argument" display text and must be quoted. skills/understand/SKILL.md is wrapped twice (["[path] ...]"]), which parses to a one-element list.

The skill spec requires argument-hint to be a string, so type validation rejects all of these.

Affected files / values

File	Current (parses as list)	Fix (string)
skills/understand/SKILL.md	["[path] [--full|--auto-update|--no-auto-update|--review|--language <lang>]"]	"[path] [--full|--auto-update|--no-auto-update|--review|--language <lang>]"
skills/understand-chat/SKILL.md	[query]	"[query]"
skills/understand-dashboard/SKILL.md	[project-path]	"[project-path]"
skills/understand-domain/SKILL.md	[--full]	"[--full]"
skills/understand-explain/SKILL.md	[file-path]	"[file-path]"
skills/understand-knowledge/SKILL.md	[wiki-directory]	"[wiki-directory]"

skills/understand-diff/SKILL.md and skills/understand-onboard/SKILL.md have no argument-hint field and load fine — no change needed.

Fix

Quote each argument-hint value so it is a YAML string. This is backward-compatible with lenient loaders. Patch (verified to apply cleanly against 2.8.0 and produce valid string frontmatter):

--- a/skills/understand/SKILL.md
+++ b/skills/understand/SKILL.md
@@ -1,5 +1,5 @@
 ---
 name: understand
 description: Analyze a codebase to produce an interactive knowledge graph for understanding architecture, components, and relationships
-argument-hint: ["[path] [--full|--auto-update|--no-auto-update|--review|--language <lang>]"]
+argument-hint: "[path] [--full|--auto-update|--no-auto-update|--review|--language <lang>]"
 ---
--- a/skills/understand-chat/SKILL.md
+++ b/skills/understand-chat/SKILL.md
@@ -1,5 +1,5 @@
 ---
 name: understand-chat
 description: Use when you need to ask questions about a codebase or understand code using a knowledge graph
-argument-hint: [query]
+argument-hint: "[query]"
 ---
--- a/skills/understand-dashboard/SKILL.md
+++ b/skills/understand-dashboard/SKILL.md
@@ -1,5 +1,5 @@
 ---
 name: understand-dashboard
 description: Launch the interactive web dashboard to visualize a codebase's knowledge graph
-argument-hint: [project-path]
+argument-hint: "[project-path]"
 ---
--- a/skills/understand-domain/SKILL.md
+++ b/skills/understand-domain/SKILL.md
@@ -1,5 +1,5 @@
 ---
 name: understand-domain
 description: Extract business domain knowledge from a codebase and generate an interactive domain flow graph. Works standalone (lightweight scan) or derives from an existing /understand knowledge graph.
-argument-hint: [--full]
+argument-hint: "[--full]"
 ---
--- a/skills/understand-explain/SKILL.md
+++ b/skills/understand-explain/SKILL.md
@@ -1,5 +1,5 @@
 ---
 name: understand-explain
 description: Use when you need a deep-dive explanation of a specific file, function, or module in the codebase
-argument-hint: [file-path]
+argument-hint: "[file-path]"
 ---
--- a/skills/understand-knowledge/SKILL.md
+++ b/skills/understand-knowledge/SKILL.md
@@ -1,5 +1,5 @@
 ---
 name: understand-knowledge
 description: Analyze a Karpathy-pattern LLM wiki knowledge base and generate an interactive knowledge graph with entity extraction, implicit relationships, and topic clustering.
-argument-hint: [wiki-directory]
+argument-hint: "[wiki-directory]"
 ---

Suggested guard (optional)

Add a CI lint that parses each SKILL.md frontmatter and asserts type(argument-hint) is str, so this regression can't reappear.

Environment

Component	Version
understand-anything plugin	2.8.0
Skill loader	GitHub Copilot CLI 1.0.65 (experimental mode enabled)
OS	Ubuntu 26.04 LTS (WSL2)
Kernel	6.18.33.1-microsoft-standard-WSL2 (x86_64)
Node.js	v26.3.0
WSL	2.7.8.0 (WSLg 1.0.73.2)
Windows	10.0.26100.8655

Note: the field-type bug is in the YAML frontmatter itself, so it is independent of OS/WSL — any loader that validates argument-hint as a string will reject these files. The environment above is just where it was observed.