docs: document the toolkit curation format and add an authoring skill - #1125
Merged
teallarson merged 1 commit intoAug 13, 2026
Conversation
Follow-up from Sergio's review of #1112, which gave hand-authored toolkit prose a home in curation/ but documented the format only by example. Adds toolkit-docs-generator/CURATION.md as the format reference: the three file kinds, every frontmatter key with allowed values and effect, a slot-order table for toolkit-level chunks and a per-location table for tool-level ones, the authoritative-directory rule, and every failure message. Reading the renderers to build those tables turned up behavior the naming contradicts, now stated explicitly: - `position` is a slot name, not a spatial relation. All four toolkit-level header/description slots render above the generated summary. - Several accepted combinations render nowhere — `replace` on description, auth, and custom_section; parameters/secrets/output at toolkit level. - Filenames don't set display order. The renderer re-sorts each slot by priority, then header, then body, ignoring array order. - `type: section` renders as a default callout, since the renderer has no case for it. - imports/ and pages/ reach the JSON but nothing in the app reads them. Adds .claude/skills/curate-toolkit-docs/ as the procedure an author or agent follows to add curation and verify it. Adds a `validate-curation` CLI command so that verification is possible without Engine credentials: it compiles the directory with the same code generation uses and reports per toolkit. To report every broken toolkit instead of dying on the first, the directory walk moves into `compileCurationDirectory`, which returns a result-or-error per toolkit; MarkdownCurationSource consumes it and still throws on the first error, so generation behavior is unchanged. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
Author
|
@BugBot review |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 1ad3c01. Configure here.
teallarson
marked this pull request as ready for review
August 12, 2026 20:11
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes GRO-278. Follow-up from @sdserranog's review of #1112:
curation/had no format reference, only examples.What's here
toolkit-docs-generator/CURATION.md— the reference. File kinds, every frontmatter key, slot-order tables, the authoritative-directory rule, and each failure message with its trigger..claude/skills/curate-toolkit-docs/— the procedure for adding or editing curation.validate-curationCLI — compiles a curation tree with the same code generation uses, so authors can check their work without Engine credentials. It can't verifytool:targets, which need the live tool list; the command says so.Documented, not changed
Writing the tables surfaced places where behavior contradicts naming. All left as-is, all now written down:
positionis a slot name, not a spatial relation —description+afterrenders above the summary.replaceon several locations;parameters/secrets/outputat toolkit level).priority. Every existing file has a001-prefix, so this misleads.type: sectionrenders as a callout — all 26 existing ones sit in boxes.imports/andpages/reach the JSON but nothing in the app reads them.Happy to file tickets if we'd rather fix any of these.
Note
compileCurationDirectoryis extracted fromMarkdownCurationSource.loadDataso validation can report every broken toolkit instead of dying on the first.loadDatastill throws on the first error, so generation is unchanged.Verification
Typecheck, lint, and 834 tests pass.
validate-curationis clean across all 75 toolkit directories, and each failure path was exercised by hand. Docs and tooling only — no rendered-page changes.🤖 Generated with Claude Code