Skip to content

docs(glossary): define bootstrap run for Skillgen #547

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
harlan-zw merged 1 commit into from
Oct 7, 2026
Merged

docs(glossary): define bootstrap run for Skillgen #547

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions GLOSSARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ Shared terms match the skilld CLI glossary (`skilld-dev/skilld/GLOSSARY.md`). Th
| behavior | `skilld-protocol/behaviors`, Skill page | Skill 1—N behavior | "Skill behaviors" |
| behavior reading | `behavior-review` check result, Skill page, skilld CLI | behavior match 1—1 behavior reading | "model reading" |
| Skillgen | `workers/skill-harness`, `/skillgen` | Repository 1—N pull request | "Skillgen" |
| bootstrap run | `workers/skill-harness`, `/skillgen` | package 1—1 bootstrap run | "bootstrap run" |
| task search | search box, `layers/registry` | sentence 1—N Skill | "Find skills for this task" |

Collisions
Expand Down Expand Up @@ -321,6 +322,16 @@ Existing route paths, table names, and protocol fields keep their identifiers.

**Casing:** `Skillgen` in prose and UI. `skilld-skillgen` only where GitHub shows the App's name.

### bootstrap run

**Is:** the first Skillgen run for an npm package that has no Skill. A separate review must accept the Skill. Then Skillgen opens a pull request that adds it, lists it in the package's `files`, and adds the skilld.dev badge to the README. If the review confirms package bugs, Skillgen also opens one issue that lists them.

**Use for:** that first run only. Each later release tag updates the Skill.

**Never:** onboarding, scaffold, first-time setup.

**Status:** planned. `docs/work/EXECUTE-skillgen-bootstrap.md` owns the work.

### guide skill

**Is:** a curation tag for a Skill not tied to a package. Distributed as a git Skill, tagged for filtering in browse views.
Expand Down
11 changes: 4 additions & 7 deletions docs/work/EXECUTE-skillgen-bootstrap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ Today Skillgen only updates an existing Skill. `prepareTag` skips with `EXISTING
- **One Skill per npm package.** A Skill ships inside its package, so npm distributes it with the version it describes. A monorepo does not get one shared Skill.
- **The bootstrap pull request adds `skills` to the package's `files`.** Without it the Skill never reaches npm. Update runs still change only the Skill directory.
- **The Harness runs OpenCode on GLM 5.3** through OpenCode Go (`opencode-go/glm-5.3`).
- **The bootstrap pull request adds the skilld.dev badge** after the README's other badges. It adds no tip.
- **Issues file automatically** and list only the package bugs a review confirmed.
- **The term is "bootstrap run".** `GLOSSARY.md` defines it.

## What the manual run showed

Expand Down Expand Up @@ -49,17 +52,11 @@ Observations that shape the design:
- [ ] **Bootstrap budget.** Measure one Harness bootstrap run on `which-nuxt` with GLM 5.3 before choosing limits. The update limits will not fit.
- [ ] **Opt-in without a Skill.** `inspectSkillgenRepository` returns `NoSkill` today. Make a public package that npm publishes eligible, and list maintained repositories with one even when the registry holds no Skill.
- [ ] **Package choice.** Store the packages a maintainer turns on per repository. Default to the root package, or to packages that no sibling package depends on.
- [ ] **Bootstrap job.** Turning a repository on queues a job for the latest tag that matches each chosen package. It reuses the provenance checks. `currentSkill` may be empty for this job kind. The destination is `skills/NAME` beside the package's `package.json`, and the pull request adds `skills` to `files`.
- [ ] **Bootstrap run.** Turning a repository on queues a job for the latest tag that matches each chosen package. It reuses the provenance checks. `currentSkill` may be empty for this job kind. The destination is `skills/NAME` beside the package's `package.json`. The pull request adds `skills` to `files` and the README badge.
- [ ] **Structured mismatches.** `skilld-harness` returns the generation's mismatches as data: expected, observed, repro, source. Review confirms or drops each one.
- [ ] **Issue publication.** Request `issues: write` for the App. File one issue per bootstrap with confirmed mismatches only. Skip quietly while an installation has not accepted the permission.
- [ ] **Copy.** `/skillgen`, `/make-skill`, and `/me?view=skillgen` say Skillgen needs an existing Skill. Update them with the opt-in change.

## Open questions

- Is "bootstrap run" the term? It would name the first Skillgen run that adds a Skill. `GLOSSARY.md` has no entry yet.
- Should a bootstrap pull request also add the README badge and tip, or only the Skill and `files`?
- Should issues wait for a maintainer to approve them on `/me?view=skillgen`, given they post to someone else's tracker?

## Log

- 2026-10-07 Manual run on five packages. Pull requests and issues are linked in the table above.
Loading