| name | contribute-story |
| description | Use when someone has created a Wander & Tales story (with the create-story skill or by hand) and wants to share it with the public library by opening a draft pull request. Needs a GitHub account. Handles the contribution trust model, prepares the branch with the content (and optionally the author's own pictures, never built PDFs), and opens a draft PR for a maintainer to review. Defers all voice and content rules to the authoring-story-content skill. Trigger on requests like "contribute my story", "open a PR with my story", "share my story upstream", "add my story to the library", or "submit my adventure". |
Sharing your story with the public library
This skill is the optional sharing step, the counterpart to create-story (which
makes your own kit) and publish-story (which the maintainer runs after a merge).
Use it when the author has a finished story and wants it added to the public library.
Sharing is entirely optional. The author already has their own printable kit from
create-story; this skill only opens a draft pull request a maintainer will review.
The trust model (state it to the author): a contribution is a draft PR carrying
the text and the image prompts, and optionally pictures the author made themselves.
Built PDFs, anything under dist/, and the maintainer's OpenAI key are never in a
contributor PR. A maintainer reviews every PR and, if it is accepted, illustrates and
publishes it. See CONTRIBUTING.md for the full contributor guidance.
Step 1: pre-flight checks
From the repository root with the virtualenv active (or prefix with .venv/bin/):
python -m build validate --root .
python -m build lint --root .
validate must say OK. lint must report no [error] lines; [warning] lines about
images with no generated file are fine for a prompts-only story (the maintainer
illustrates after acceptance). Confirm the story keeps the ethos the maintainer will
check: nobody loses, difficulty bands not specific dice, canon-consistent names,
associational (not causal) claims in grown-up copy, no em or en dashes, and the
reading level matching each file. The authoring-story-content skill holds these
rules.
Step 2: decide what goes in the PR
- Always include: the content under
worlds/<world>/ (the story.yaml, the
per-locale prose, the world-level idea bank, and for a new world the world.yaml and
canon/), plus guide/<locale>/guide.md only if the author changed the generic
Guide.
- Optionally include: pictures the author made themselves (or generated with their
own key), dropped in as
worlds/<world>/**/assets/<image-id>.png. The PR will ask
the author to confirm the art is theirs to give. A hand-drawn map
(worlds/<world>/stories/<story>/assets/map.svg) counts as art too; include it only
if it is the author's own. No map file is needed otherwise: the build generates a
trail map from the story's stop headings, so the map ships from the content alone.
- Never include: built PDFs, anything under
dist/, or the maintainer's key. The
story catalogue and README links are regenerated by the maintainer's rebuild after
merge, so the contributor does not touch them.
Step 3: branch, commit, and push
git checkout -b story/<world>-<story>
git add worlds/<world>
git status
git commit -m "story: <Story Title> in <World>"
git push -u origin story/<world>-<story>
Step 4: open a draft pull request
Open the PR as a draft with the repository template
(.github/pull_request_template.md). Use the GitHub CLI:
gh pr create --draft \
--title "story: <Story Title> in <World>" \
--body-file <(cat <<'BODY'
<paste the filled PR body here>
BODY
)
If gh is not authenticated (gh auth status) or the GitHub MCP is not available, do
not guess: print the pushed branch name and tell the author to run gh auth login and
retry, or open the PR in the web UI from their branch (the template pre-fills the
checklist there).
Fill the PR body from the template. At minimum state: the world and story; which
locales were authored, and that any non-English text is machine-drafted and may need a
native review; whether art is included and, if so, that it is the author's to give;
and tick the quality checklist (nobody loses, bands not dice, canon-consistent names,
associational claims, no dashes, reading level matches the file). Note that a
maintainer will review, may request changes, and may regenerate or replace the art.
Step 5: what happens next
Tell the author: a maintainer reviews the PR, may request changes, and if it is
accepted will illustrate (with the maintainer's own key) and publish it into the
library via the publish-story flow. The author keeps their own kit regardless.
Quick checklist before you call it submitted
validate passes and lint has no errors.- The branch holds the content (and only the author's own art, if any), with no
dist/
and no built PDFs.
- The PR is a draft, titled
story: <Title> in <World>, with the template filled.
- The maintainer's OpenAI key was never used or referenced.
