← Back to guides

Submit your tool

TinkerBox tools are added by GitHub pull request — there is no in-app submission form.

Steps

  • Fork or branch this repo. PRs come from a branch or fork of the TinkerBox repo — that's the only way CI can validate your tool before it ships.
  • **Add tools/<slug>.yaml.** One file per tool keeps the catalog diffable and makes duplicate detection possible in CI.
  • **Match the filename to the slug field exactly.** The catalog fails closed on a mismatch instead of silently renaming your file — that keeps URLs and slugs predictable.
  • Fill in the required fields: slug, name, description, intended_users, repository_url. Every field is required because the catalog and detail page both render straight from it — a missing field means a broken card.
  • **Point repository_url at https://github.com/tiptipid/....** Locking to one org means there's always someone TinkerBox can reach if a tool needs fixing.
  • Open a PR. validate-tools runs schema and duplicate-slug checks automatically. Once it's green, a maintainer merges it — every PR gets a human merge, so nothing reaches the catalog unseen. Your tool goes live on the deploy that follows.

Example

slug: my-experiment
name: My Experiment
description: One-line summary of what it does (max 160 characters).
intended_users:
  - engineer
  - all
repository_url: https://github.com/tiptipid/my-experiment
website_url: https://example.com
thumbnail_url: https://example.com/thumb.png

Need org access first? See Get Access.