feat(author): the hand-over carries the source file, the build page link and where to say how it went
Closes #190.
A chat that builds the package itself hands it over in the chat, and its user never sees the build page and its "How did it go?". On 0.9.4's text, Haiku with the skill, a shell and npm handed the source over as a file in 2 of 3 runs, unasked, and never a link to the build page or where to say how it went.
What changes
SKILL.md, step 5 hands over, beside the package:- the source as a file under the package's name with
.source.json(course.source.json), copied as the package was, and the files it names, said by name, since a build reads them beside it; the build page opens the source file too; - what step 3's command printed for this source: the build page's link that carries it, where the user plays the package in any browser, changes the source and builds it again, and in every case the line where they can say how it went. A link is still only what a command printed.
- the source as a file under the package's name with
- Step 3's two commands, Node's and Python's, print a second line under the link:
How did it go? Say so by email or on GitHub: https://missing-elements.github.io/h5p/build/#feedback-heading. For a source that names a file (anypath) they print that line alone: a link carries the source's text, not its files. In the build page's route such a source goes over whole, to be pasted, its files chosen on the page. Both commands run as written: each link decodes to the source byte for byte, and both print the same for a source with files. - The skill names no product. The build routes said "Claude Code", "ChatGPT" and "Gemini"; they now say what each environment can do, and what a name carried stays as what an agent can observe: the registry's errors, a sandbox that downloads only what a browsing tool has opened, a code tool that can be unavailable for hours.
design/author.mdsays why and what was measured, in two rules. Its count of rules said "Nineteen" with 22 there before these; it now says twenty-four.
The feedback address is the build page's own section, so where feedback goes (email first, or a GitHub discussion) stays the org site's to change, in one place, and the page must keep the id. A fragment without source builds nothing there (sourceFromFragment reads source alone); opened in Chromium at 1280 and 390 px wide, "How did it go?" is in view once the page has settled, with no error.
cubic's review
- Files a source names (P2): right about the link, which carries the source's text only. The page asks for those files by name, but a link cannot bring them, and a picture at a web address reaches the page only where its host lets another site fetch it. So such a source gets no link, decided by the source and not by its type: nearly every type takes media, and most sources name none.
- Not taken: copying the media beside the
.source.json. A video can be large, and the files are the user's already; the hand-over names them instead.
Tested
Haiku in Claude Code's place: the skill, a shell, npm, the verifier left out (no browser), the author and licence given. A script read each run's reply and files: the source file beside the package and equal to the one built, every build page link decoded and held to that source, the feedback address, and for a source with a picture, that no link was given and the picture was named.
A three-question Question Set:
| Skill text | Runs | Source file | Link that decodes to the source | Where to say how it went |
|---|---|---|---|---|
| 0.9.4 | 3 | 2 | 0 | 0 |
| The feedback line last in step 5's list | 3 | 3 | 3 | 2 |
| The feedback line third in the list | 3 | 3 | 3 | 1 |
| "End the reply with" it | 4 | 4 | 4 | 3 |
| Printed by step 3's command under the link | 4 | 4 | 4 | 3; the fourth sent the user to the link's page |
| This PR: printed by the command, "in every case" in step 5 | 2 | 2 | 2 | 2 |
One Multiple Choice question with the user's drawing above it:
| Skill text | Runs | Source file | No link | Picture named | Where to say how it went |
|---|---|---|---|---|---|
| The commands print why there is no link, then the feedback line | 3 | 3 | 3 | 3 | 0 |
| This PR: the feedback line alone | 3 | 3 | 3 | 2 | 3 |
The links were 1,200 to 1,520 characters for three questions. A weak model shortens step 5's list as it writes it out, while what a command printed reaches the reply: a link always, and the line under it, but a line explaining why there was no link was written in the model's own words with the address left out. A first round with a picture of the project's banner was dropped: Haiku looked at the picture and refused to put it above a question about river deltas, and the drawing used instead matches its question.
No test covers SKILL.md's text; CI runs the suites.
After merge
- h5p-author 0.9.5, a patch (the skill's text), then the org site's pin, for chats that read the skill by link.
npx skills update -g, and a new zip for the Claude app.
Not verified
- The Claude app's sandbox and other chat apps: only Haiku in a shell was run, so the routes reworded without app names were not run in the apps they describe.
- A long source: a book's link was not tried.
Summary by cubic
The skill's hand-over now carries the source file, the build page link, and where to say how it went, so a chat that builds the package itself gives its user the same play, rebuild, and feedback options the build page offers.
- Step 5 hands over the source as a
.source.jsonfile beside the package, plus both lines step 3's command now prints: the build page link carrying the source, and the feedback address under it. - A link carries a source's text, not the files it names, so for a source that names files step 3's commands print the feedback line alone, step 5 hands it over in every case, and the build page route gives such a source whole for pasting.
- The build routes now describe what each environment needs (a shell reaching the npm registry, Node with fetching, or a browser) instead of naming products.
- Measured on Haiku: all 14 runs handed over the source file and a working link; the feedback line reached 3 of 4 replies, with the fourth sent to the link's page.
design/author.mddocuments why, and its rule count updates from nineteen to twenty-four.