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.

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 hugo-site/content/… (or content/… if the Hugo site lives at the repo root).
4. Preview locally with hugo server -D (see Running the site locally).
5. Open a PR against main on stevologic/agentic-remediation-recipes.
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>/agentic-remediation-recipes.git
cd agentic-remediation-recipes

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/agentic-remediation-recipes.git
git fetch upstream

4. Create a branch

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

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/agentic-remediation-recipes: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 Hugo 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 <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 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 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.

Use the archetype to scaffold:

cd hugo-site
hugo new 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 pricing are dated so the reader knows when the page might have drifted.

Contributing a prompt

The Prompt Library is organised by tool:

content/prompt-library/
├── claude/
├── codex/
├── cursor/
├── 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 general/.

Template

Every prompt file uses the same frontmatter:

---
title: "<Short, descriptive name — e.g. 'Claude CVE triage skill'>"
tool: "<claude | copilot | cursor | codex | 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.

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, Hugo + Hextra shortcodes. The {{< callout >}}, {{< relref >}}, and {{< cards >}} 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 {{< relref "/<section>" >}} for internal links so Hugo validates them 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:

• Hugo extended >= 0.139
• Go >= 1.21 (Hextra is a Hugo Module)
• Git

hugo mod get -u github.com/imfing/hextra
hugo mod tidy
hugo server -D --disableFastRender
# → http://localhost:1313

Prefer Docker?

docker build -t arr .
docker run --rm -p 3000:80 arr
# → 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.