Skip to content

Commit 1ad3c01

Browse files
teallarsonclaude
teallarson
and
claude
committed
docs: document the toolkit curation format and add an authoring skill
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>
1 parent e018ac3 commit 1ad3c01

7 files changed

Lines changed: 662 additions & 45 deletions

File tree

‎.claude/skills/curate-toolkit-docs/SKILL.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
name: curate-toolkit-docs
3+
description: Add or edit hand-authored prose on an Arcade toolkit reference page by writing curation files under toolkit-docs-generator/curation/. Use when asked to document a toolkit's auth setup, explain an enum or parameter, add a warning to a tool, or fix wording on a toolkit page — anything where the text belongs to a specific toolkit or tool rather than a standalone docs page.
4+
---
5+
6+
# Curating toolkit docs
7+
8+
Toolkit reference pages are generated. Editing the JSON under
9+
`toolkit-docs-generator/data/toolkits/` does nothing durable — the next
10+
generation run overwrites it. Hand-written prose lives in
11+
`toolkit-docs-generator/curation/<toolkit>/` and is folded into the JSON on
12+
every run.
13+
14+
`toolkit-docs-generator/CURATION.md` is the format reference. This is the
15+
procedure.
16+
17+
## Step 1: confirm curation is the right home
18+
19+
Curation is for prose bound to one toolkit or one tool: auth setup, enum value
20+
tables, parameter caveats, per-tool warnings. If the content is a standalone
21+
guide or concept explanation — anything a reader would reach from the sidebar
22+
on its own — it belongs in `app/en/` as a normal MDX page instead. Stop and
23+
write that page.
24+
25+
## Step 2: read the neighbors
26+
27+
```bash
28+
ls toolkit-docs-generator/curation/
29+
cat toolkit-docs-generator/curation/googleflights/chunks/*.mdx
30+
```
31+
32+
Directory names are lowercase and stripped of punctuation: `GoogleFlights` →
33+
`googleflights`. Create one if the toolkit has none. Toolkits in the same family
34+
usually share a pattern, and most existing auth prose is close to what you need.
35+
36+
## Step 3: pick the file kind
37+
38+
Use `chunks/*.mdx` — a block injected into the toolkit page or one tool's
39+
section. That's the right answer in almost every case. The other two kinds,
40+
`imports/*.mdx` and `pages/**/*.mdx`, are validated and carried into the JSON
41+
but nothing in the app reads them, so don't reach for either expecting it to
42+
render.
43+
44+
Name the file with a numeric prefix and a slug matching the neighbors, for
45+
example `003-auth-after-markdown.mdx`. The number is for humans and does not
46+
control display order.
47+
48+
## Step 4: choose `location` and `position`
49+
50+
Toolkit-level (no `tool:` key):
51+
52+
| You want it | Use |
53+
| --- | --- |
54+
| Right under the title, above the generated summary | `location: header`, `position: before` |
55+
| Auth setup, after the summary | `location: auth`, `position: after` |
56+
| A reference section between the summary and the tools table | `location: custom_section`, `position: after` |
57+
| Just above the tools table | `location: before_available_tools`, `position: after` |
58+
| Below the tools table, above the per-tool sections | `location: after_available_tools`, `position: after` |
59+
60+
`position` is a slot name, not a spatial relationship — `description` + `after`
61+
still renders above the generated summary. Check the ordering table in
62+
`CURATION.md` before assuming a combination does what its name suggests. Some
63+
render nowhere at all, and the compiler accepts them silently.
64+
65+
Tool-level: add `tool: Toolkit.ToolName`, fully qualified, same toolkit as the
66+
directory. Then `location` is one of `description`, `parameters`, `secrets`,
67+
`auth`, or `output`, and `position: replace` suppresses that default block. One
68+
pitfall: a tool-level `auth` chunk only renders for tools that have OAuth
69+
scopes, and only after the reader expands the scope details. If the prose
70+
matters to every reader, make it a toolkit-level `auth` chunk.
71+
72+
## Step 5: write the file
73+
74+
```mdx
75+
---
76+
type: markdown
77+
location: custom_section
78+
position: after
79+
header: "## GoogleFlightsTravelClass"
80+
---
81+
82+
## GoogleFlightsTravelClass
83+
84+
Cabin class for the search.
85+
86+
- **`ECONOMY`**: Economy cabin.
87+
- **`BUSINESS`**: Business cabin.
88+
```
89+
90+
Rules that bite:
91+
92+
- `type: markdown` renders flat. `callout`, `warning`, `info`, and `tip` wrap
93+
the body in a callout box, and so does `section` despite its name — use
94+
`markdown` for flat prose.
95+
- `header` sets the anchor and section-nav entry but prints nothing. Repeat the
96+
heading in the body, as in the example.
97+
- Order within a slot comes from `priority` (lower first, default `100`), not
98+
from filenames.
99+
- `Callout`, `Steps`, `Tabs`, `TabbedCodeBlock`, `TableOfContents`,
100+
`ToolFooter`, `SignupLink`, and `DataTable` work without importing. Any other
101+
component fails to render.
102+
- Unknown frontmatter keys fail the run. There is no `language`, `slug`, or
103+
`order` key.
104+
- Follow `STYLEGUIDE.md`: sentence case headings, active voice, "Arcade
105+
Engine", "MCP server", "tool".
106+
107+
To delete prose, delete the file — the curation directory is authoritative, so
108+
removing the last file for a toolkit clears its prose on the next run.
109+
110+
## Step 6: verify before committing
111+
112+
Always run this. No credentials needed:
113+
114+
```bash
115+
cd toolkit-docs-generator
116+
../node_modules/.bin/tsx src/cli/index.ts validate-curation --toolkit <ToolkitId>
117+
```
118+
119+
Errors name the exact file and reason. Then `pnpm vale:check` from the repo
120+
root.
121+
122+
If you used `tool:`, confirm the value against the generated JSON, where
123+
`qualifiedName` is exactly the format the frontmatter wants. A wrong value
124+
fails the generation workflow, not your local check.
125+
126+
```bash
127+
grep -o '"qualifiedName": "[^"]*"' toolkit-docs-generator/data/toolkits/googleflights.json
128+
```
129+
130+
## Step 7: set expectations in the PR
131+
132+
The rendered page will not change in the PR's preview deploy — curation only
133+
reaches the site when the generation workflow next runs and opens its automated
134+
docs PR. Say so in the description so a reviewer doesn't hunt for a visual
135+
diff. A local preview needs generated JSON, which needs Engine credentials —
136+
see the last section of `CURATION.md`.

‎toolkit-docs-generator/ARCHITECTURE.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@ The generator does **not** render HTML. It produces structured JSON and optional
2727
- `MarkdownCurationSource` compiles documentation chunks, import declarations,
2828
and subpages from the configured curation directory. When configured, that
2929
directory is globally authoritative: a missing toolkit directory means the
30-
toolkit has no authored curation.
30+
toolkit has no authored curation. [CURATION.md](CURATION.md) documents the
31+
file format it accepts.
3132
- `CombinedToolkitDataSource` merges tools and metadata into one interface.
3233

3334
### Merger
@@ -94,6 +95,7 @@ public, read-only values configured through these Vercel environment variables:
9495

9596
- `src/sources/engine-api.ts` — tool metadata from Engine API
9697
- `src/sources/markdown-curation.ts` — Markdown and MDX curation compiler
98+
([format reference](CURATION.md))
9799
- `src/sources/toolkit-data-source.ts` — unified data source
98100
- `src/merger/data-merger.ts` — merge pipeline
99101
- `src/generator/json-generator.ts` — output writer

0 commit comments

Comments
 (0)