Contribute

Thanks for wanting to contribute! This project is community-driven — we grow faster the more teams share back the recipes, prompts, and guardrails that are working for them.

The same guide lives at CONTRIBUTING.md in the repo root, so GitHub’s “Contribute” button points at it. The two copies are intentionally redundant.

TL;DR

  1. Fork the repo on GitHub.
  2. Branch off main — recipe/<tool>-<topic> or prompt/<tool>/<short-name>.
  3. Make your change under the root-level content/… directory.
  4. Preview locally from the repo root with npm run serve (see Running the site locally).
  5. Open a PR against main on stevologic/security-recipes.ai.
  6. Get one reviewer from Security and one from the team that owns the prompt or recipe.
  7. On merge, the GitHub Actions workflow rebuilds the site and pushes to gh-pages automatically — no manual deploy.

Fork-and-PR workflow

We use the classic GitHub fork-and-PR model. You do not need push access to the upstream repo to contribute.

1. Fork

From the repository page on GitHub, click Fork (top right) and pick your own account or a team org.

2. Clone your fork

git clone https://github.com/<your-user>/security-recipes.ai.git
cd security-recipes.ai

3. Add the upstream remote

This lets you pull new changes from the canonical repo into your fork.

git remote add upstream https://github.com/stevologic/security-recipes.ai.git
git fetch upstream

4. Create a branch

Branch names should read like commit messages. Prefixes we use:

Prefix Use
recipe/ New or updated per-agent recipe
prompt/ New or updated Recipes entry
docs/ Non-recipe documentation
chore/ Build, CI, deps, infra
fix/ Bug fixes (broken links, typos, wrong snippets) 
git checkout -b prompt/claude/cve-triage upstream/main

5. Commit and push

Keep commits focused. Imperative mood, reference the recipe or prompt in the subject line:

Add Claude CVE-triage skill with transitive-dep guardrails

Closes #42.
git add content/...
git commit
git push origin prompt/claude/cve-triage

6. Open a PR against main

Open a pull request from your branch to stevologic/security-recipes.ai:main. The PR template prompts for the four things reviewers check:

  • What the recipe or prompt does
  • Why it belongs here (not a personal wiki)
  • Where it’s been running in production (team + service)
  • Known limits — honest failure modes, not a pitch

7. Address review and merge

Squash-merge is the default. Once merged, the GH Actions pipeline builds the site and publishes gh-pages in about a minute.

Keeping your fork in sync

Periodically:

git checkout main
git fetch upstream
git merge upstream/main
git push origin main

What you can contribute

Anything that makes agentic remediation more reliable, reviewable, or repeatable for the next team:

  • A new agent recipe — your content/<tool>/_index.md playbook.
  • An update to an existing recipe — new guardrails, new failure mode, new verification step.
  • A prompt, rules file, or skill — drop under content/prompt-library/<tool>/.
  • A CVE recipe prompt — drop under content/prompt-library/cve/ when a named CVE needs a specific remediation prompt.
  • A fix — broken link, wrong command, outdated screenshot.
  • An issue — file one if you spot something broken and don’t have time to fix it yourself; the template asks for repro steps.

Contributing marketplace integrations and workflow packs

The browser workbench marketplace is also contributed content.

If you are adding a new connector pack, report contract, or workflow bundle:

  • edit the matching site data file under data/marketplace/
  • keep the runtime state honest: live, live_or_copy, copy_only, config_only, or planned
  • document the auth shape, browser/CORS assumptions, and human-review expectation on a docs page
  • include an example target system and example scope so reviewers can validate the payload shape
  • validate browser-authored submission packets against the published schema files under static/marketplace-schemas/ or the generated /marketplace-schemas/*.json URLs before opening the PR

The marketplace files are split on purpose:

  • data/marketplace/input_channels.json - context and scanner intake
  • data/marketplace/output_channels.json - downstream delivery routes
  • data/marketplace/report_profiles.json - normalized output contracts
  • data/marketplace/workflow_templates.json - reusable bundles stitched from the above

For public discoverability, update the Marketplace and Workflow Gallery when your PR changes how a pack should be explained to operators.

The site build also emits public JSON feeds from the same source files, so downstream tooling can consume marketplace contracts without scraping the page UI. Keep the data files authoritative; do not hand-edit generated feed outputs elsewhere.

If you are starting from the browser workbench instead of hand-authoring JSON:

  • use the Workflow Pack Lab in the Control Plane tab to clone a pack or capture the current agent planner configuration
  • save it locally until the pack shape feels stable
  • use Validate draft so the contribution packet matches the published workflow schema before you export it
  • copy the generated contribution packet, then paste the template object into data/marketplace/workflow_templates.json
  • include the operator story, auth assumptions, browser/CORS expectations, and review gate in your PR description or companion docs update

If you are contributing a report contract from the browser workbench:

  • use the Report Profile Lab in the Control Plane tab to clone or author the report profile locally
  • capture the intended sections, output format, and example JSON payload before you export it
  • use Validate draft so the contribution packet matches the published report-profile schema before you export it
  • copy the generated contribution packet, then paste the profile object into data/marketplace/report_profiles.json
  • document which downstream systems or reviewers consume the report, and what evidence the contract is expected to carry

If you are contributing an input or output integration pack from the browser workbench instead of hand-authoring JSON:

  • use the Integration Pack Lab in the Control Plane tab to clone or author the pack locally
  • save the draft in browser storage while you refine the runtime support, auth modes, and config JSON
  • use Validate draft so the contribution packet matches the published input/output schema before you export it
  • use Copy submission for the specific pack, then paste the channel object into data/marketplace/input_channels.json or data/marketplace/output_channels.json
  • use the local library copy/download actions if you need to move private input, output, report, or workflow contracts between browser profiles before opening the PR
  • if you import a portable local library, keep it on the schema-backed /marketplace-schemas/local-library.schema.json contract so the browser can validate it before merging it into local storage

For browser-local asset and ownership libraries:

  • use the Asset and Ownership Board to capture repositories, services, hosts, APIs, or tenants with owner-team and criticality metadata
  • keep import/export payloads on the schema-backed /marketplace-schemas/asset-library.schema.json contract
  • include portfolio IDs / labels when multiple repositories, APIs, or stores should roll up into one service-level queue
  • use related asset IDs when reviewers should be able to reconstruct a lightweight service map from the exported library
  • include the matching aliases you expect reviewers to validate, especially when a record is supposed to enrich Exposure Board routing

For browser-local routing policy libraries:

  • use the Routing Policy Lab to capture severity, criticality, source, workflow, owner, portfolio, environment, and downstream default logic locally first
  • keep single-policy exports on /marketplace-schemas/routing-policy.schema.json
  • keep full routing-library backups on /marketplace-schemas/routing-library.schema.json
  • document which downstream defaults reviewers should expect, especially when a policy is meant to prefill Jira project, Linear team, ServiceNow table, Elastic owner, or Splunk index settings
  • include the expected explainability outcome in the PR notes: which match signals should fire, which route/report/review defaults should appear, and whether the recommended route should already be browser-ready or remain a template/local-only path

For private browser investigations, use the same discipline even though Caseboard exports are not public marketplace contributions:

  • keep single-case exports on /marketplace-schemas/case-file.schema.json
  • keep whole Caseboard backups on /marketplace-schemas/case-library.schema.json
  • validate before handing saved investigations to another reviewer, tool, or browser profile

Contributing a new agent recipe

A “recipe” is a per-tool playbook. Every recipe follows the same four-section skeleton so teams can skim and compare:

  1. Prerequisites — licenses, accounts, integrations required first.
  2. Recipe steps — a numbered, opinionated walkthrough. No “it depends.”
  3. Verification — how to know end-to-end that it worked.
  4. Guardrails — the controls in place before you scale it up.

Scaffold a new recipe by creating the page and its frontmatter:

mkdir -p content/<tool>
$EDITOR content/<tool>/_index.md

Things reviewers look for in a recipe PR:

  • Reproducible — a peer followed it and got the same result.
  • Opinionated — you picked one path and explained the trade-off.
  • Safe — the Guardrails section is not an afterthought.
  • Current — versions and plan documentation are dated so the reader knows when the page might have drifted.

Contributing a prompt

Recipes are organised by tool:

content/prompt-library/
├── claude/
├── codex/
├── cursor/
├── cve/              # per-CVE remediation prompts and recipes
├── devin/
├── general/          # tool-agnostic prompts, patterns, hooks
└── github_copilot/

Drop your file in the subdirectory that matches the agent it targets. If it’s tool-agnostic (e.g. a triage framework you use across every agent), put it in content/prompt-library/general/. If it is anchored to a specific CVE, put it in content/prompt-library/cve/ so it appears in the CVE Recipes catalogue.

Template

Every prompt file uses the same frontmatter:

---
title: "<Short, descriptive name — e.g. 'Claude CVE triage skill'>"
tool: "<claude | copilot | cursor | codex | cve | devin | general>"
author: "<your @handle>"
team: "<team name>"
maturity: "<experimental | production>"
model: "<model string you ran this on — e.g. Opus 4.7, gpt-5-codex>"
tags: ["triage", "sca", "..."]
weight: 99
---

## What this prompt does

One paragraph. What goes in, what comes out, what's the happy path.

## When to use it

Concrete trigger. "When a new Dependabot PR fails CI because the
breaking change wasn't auto-resolved."

## The prompt

    <the actual prompt, skill body, or rules file — fenced>

## Known limitations

2–3 cases where it misbehaves and what to do about them.

## Changelog

- YYYY-MM-DD — v1, first published.

Want to see the template in action? The Claude CVE triage skill is a fully worked example.

CVE recipe prompts

CVE recipe prompts live under content/prompt-library/cve/. Use this section when the prompt is tied to a named vulnerability and needs specific remediation guidance beyond the generic vulnerable-dependency workflow.

Name the file after the CVE and a short slug:

content/prompt-library/cve/cve-YYYY-NNNN-short-name.md

In addition to the standard prompt frontmatter, include the CVE fields that power the catalogue:

cve: "CVE-YYYY-NNNN"
known_as: ["Popular Name"]
kev: false
severity: "high"
ecosystem: "language/package-manager"
disclosed: "YYYY-MM-DD"

A good CVE recipe prompt explains the affected versions, the indicator-of-exposure, the remediation strategy, stop conditions, and the exact verification steps a reviewer can run.

What does not belong

  • Secrets, API tokens, internal hostnames, customer data. Scrub before opening the PR. This is public community-driven.
  • One-shot prompts you used once. If it’s not earning its keep, it’s not ready.
  • “Clever” jailbreaks. This library is for trustworthy, reviewable automation.

Style and conventions

  • Markdown with the site’s shortcodes. The �SRFENCE13 , �SRFENCE14 , and �SRFENCE15 shortcodes are the main ones you’ll use.
  • Line length — soft-wrap around 80 chars in prose, unless the line is a long URL or code.
  • Links — prefer �SRFENCE16 for internal links so they resolve to canonical URLs at build time.
  • Commands — fenced with the language hint (```bash, ```yaml, etc.) so syntax highlighting kicks in.
  • Weight — per-section ordering uses the weight frontmatter field. Keep within the existing ranges to avoid reshuffling the sidebar.
  • Dates — absolute, ISO-8601 (2026-04-21), never “last week.”

Review expectations

A PR needs two approvals to merge:

  1. Security — at least one reviewer from the security team. They check for safe guardrails, no leaked secrets, and that the recipe doesn’t inadvertently create a worse problem than the finding it’s fixing.
  2. Owning team — at least one reviewer from the team that will be on-the-hook for the prompt or recipe. This is the sanity check that it actually reflects how the team works.

Expected turnaround is 3 business days for a first review. Ping the reviewers in chat if it’s been longer — PRs go stale fast.

Running the site locally

Prereqs:

Run these from the repository root:

npm install                  # install the Eleventy toolchain
npm run serve                # → http://localhost:8080, incremental rebuilds

Prefer Docker?

docker build -t security-recipes .
docker run --rm -p 3000:80 security-recipes
# → http://localhost:3000

Security and sensitive data

This repository is public community-driven. Before opening a PR:

  • No customer data, PII, or production hostnames.
  • No API keys, tokens, session cookies, or signed URLs.
  • No internal-only URLs (Jira ticket IDs, internal wiki links) — link to the public equivalent if one exists, or drop the link.
  • When in doubt, ask Security to review before opening the PR.

If you spot a security issue in the repo itself (leaked token in history, live secret in a config), do not open a public issue. Email security@<your-org>.com and we’ll triage privately.

License

By contributing, you agree that your contributions will be licensed under the MIT License — the same terms as the rest of the project.