[meta-feedback] tree-generator (mixed)

[KyleAMathews]

Meta-Skill Feedback: tree-generator

Library: typography.js
Agent: claude-code
Artifact quality: mixed
Rating: mixed

What Worked

The skill type taxonomy (core, sub-skill, framework, lifecycle, composition, security) is well-designed. The flat vs nested structure guidance is helpful. The monorepo layout with package field is practical.

What Failed

The full YAML schema for skill_tree.yaml (library, generated_from, generated_at, per-skill fields) was only in the tree-generator SKILL.md — not in the scaffold summary. Without loading the actual meta skill, the AI produces a freeform YAML that doesn't match. The scaffold says "Run npx @tanstack/intent validate in each package directory" but the validate CLI actually expects the skills/ directory path, not the package root — this caused a validation failure. Had to rewrite the skill tree after reading the actual spec. Description character limit (1024 chars per Claude Skills standard) is not documented or enforced by the validator.

Suggestions

Scaffold should explicitly say: "Load node_modules/@tanstack/intent/meta/tree-generator/SKILL.md and follow its YAML schema exactly." Fix validate command docs: "Run npx @tanstack/intent validate " (e.g. packages/typography/skills, not packages/typography/). Include a minimal YAML example in the scaffold prompt so the AI has the schema without needing to load the full spec. Add description character limit validation (1024 chars) to the validator.

[KyleAMathews]

Additional feedback: validator should check package setup

During our scaffold we completed all the SKILL.md files, ran npx @tanstack/intent validate (passed), and moved on — completely forgetting to:

1. Add @tanstack/intent as a devDependency
2. Create the bin/intent.js shim
3. Add "bin" entry to package.json
4. Add "skills", "bin", and "!skills/_artifacts" to the "files" array

The scaffold checklist mentions these at the very end, but by that point the AI has moved on to feedback collection and doesn't look back. validate passing gives a false sense of "we're done."

Suggestion: npx @tanstack/intent validate should check more than just SKILL.md structure. It should also verify:

• @tanstack/intent is in devDependencies
• bin/intent.js exists
• package.json has a "bin" entry pointing to the shim
• "skills" and "bin" are in the "files" array
• "!skills/_artifacts" is in the "files" array (for monorepos)

These are the things that determine whether skills actually ship to consumers. Structural validity of SKILL.md files is necessary but not sufficient — the packaging setup is equally important and easy to forget.

[KyleAMathews]

Two more issues found during package setup

1. intent list doesn't show file paths to SKILL.md files

The list output shows skill names, types, and descriptions — but not the actual file path an agent needs to load the skill. An AI coding agent seeing this output has no way to know the path is node_modules/typography/skills/typography-core/SKILL.md. It should show something like:

typography-core  [core]  skills/typography-core/SKILL.md
  Core mental model for typography.js...

Without paths, the list is informational but not actionable for agents.

2. setup --shim generates ESM syntax in a .js file

The generated bin/intent.js uses top-level await (ESM syntax), but many packages don't have "type": "module" in package.json. This produces a Node.js warning:

Warning: Module type of file:///…/bin/intent.js is not specified and it doesn't parse as CommonJS.
Reparsing as ES module because module syntax was detected.

Fix: The shim should be generated as bin/intent.mjs (and the setup instructions should reference .mjs), or the setup command should check for "type": "module" and choose the right extension accordingly.