Skip to main content

Contributing

Thanks for helping. This section explains how to set up, what a change must meet, how to test it, and how to improve these docs. The repository's own CONTRIBUTING.md is the maintainers' reference; these pages follow it.

Ground rules in one minute​

  1. No framework or domain knowledge in the core. Router conventions go in hintpacks/ as YAML. Deleting hintpacks/ must leave a working tool.
  2. No MCP servers, no client installs. Generated skills run with the AI's built-in browser and nothing else.
  3. Code-only generation is the default. The Playwright probe is optional and only runs with --xy or --url.
  4. Every fact has a source and a confidence. Evidence never reaches a skill.
  5. No secrets or real personal data, anywhere: fixtures, tests, logs, examples. Use example.com, 555-0100 style numbers and obviously fake names.
  6. No command may prompt or wait for input. An agent runs every command.

Before you open a pull request​

Run all four; CI runs the same.

uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest
uv run pytest -m browser      # if you touched fill.js, probe/ or tests/bench/

If your change affects generated output, also run the test bench in Claude or Cowork, and paste its results table into the pull request.

Development setupClone, sync with uv, and install your working copy globally.Coding standardsNaming, functions, docstrings, errors, logging, and the pure core.TestingUnit, golden, browser and bench tests: what each covers.Adding a commandParser, schema, tests and two documents, in the same pull request.Framework supportTeach skillgen a router with a YAML hint pack and a tiny fixture.Improving these docsEdit Markdown, preview locally, and how merged changes deploy.Commits with GitsmithConventional Commits made easy with a .commitconfig.json.

Commits and pull requests​

  • Conventional Commits: feat:, fix:, docs:, test:, refactor:, chore:. Gitsmith can prompt you through them.
  • Small commits, one change each.
  • Never commit .skillgen/secrets/, .env files or Playwright storage states.
  • Record design decisions in docs/decisions.md.
  • If something in the spec is unclear, open an issue and ask before building.

By contributing you agree that your contribution is licensed under the Apache License 2.0.