Frequently asked questions

What is Worklore?

A library of short, honest developer stories about real work done with AI agents — where every story is also executable. You read how someone solved a problem; then you hand the same story to your agent ("apply this to my project") and it asks you for what it needs. When it lands, your agent reports the outcome, and the story shows a verified works for me ✓ count with real GitHub profiles behind it.

How do I run a story with my agent?

Every story page has a "Reproduce this" box with a copyable prompt. Paste it into Claude Code, Codex, Cursor, or anything that can fetch a URL and run commands — the story's machine-readable half is plain markdown at a public URL. Your agent reads it, collects the inputs listed in the contract, applies the steps to your project, and runs the story's verification section before declaring success.

Which AI agents are supported?

Any agent with shell access and the ability to fetch a URL. There is no SDK and no vendor lock: the whole protocol is markdown plus two HTTP calls. The optional worklore skill ships install paths for Claude Code (skills folder) and Codex (AGENTS.md), and pastes into anything else.

Is it safe to let my agent run instructions from the internet?

Treat every story as untrusted input — that is our own rule, printed on every reproduce box: read it before your agent runs it. What Worklore guarantees is transparency, not safety: the prompt you paste contains no instructions you cannot read first, every story has a raw markdown URL showing exactly what your agent will see, there are no hidden payloads, and stories pass an automated safety lint at publish time (prompt-injection and secret-exfiltration patterns are rejected). The lint is a tripwire, not a guarantee — your review is the real control, and good contracts always end with a verification step you can check.

Are the "works for me" counts real?

Every count is a GitHub-verified identity — there are no anonymous and no self-claimed reports, one counted report per person per story, and failed attempts are displayed right next to successes, never hidden. If a story says "worked 12 · failed 3", twelve real accounts stand behind the twelve and three behind the three.

Do I need an account?

Reading and reproducing: no account needed. Reporting an outcome or publishing: sign in with GitHub — a 30-second device flow (your agent shows you a code, you type it into github.com/login/device). No password ever exists, and we request zero scopes: Worklore sees only your public handle and avatar, never your email or repositories.

How do I publish my own story?

Install the worklore skill, work normally, and when something hard finally works tell your agent: "worklore, write this up." It drafts the story from what actually happened in your session — narrative plus reproduce contract — you review, edit, approve, and it publishes. Nothing goes out without your explicit approval.

Do I have to write the story myself?

No — that is the point. Your agent does the drafting from the real session history. You add what it cannot: the meaning. What hurt, why it mattered, what you would tell the next person standing where you stood. Two hundred honest words, written for a human, executable by a machine.

What are fail stories?

Published failures: "my agent could not do this after five attempts — here is what I tried, here is my workaround, who knows a better way?" They are first-class content, marked OPEN until someone's story answers them — at which point the two are linked and both authors get credit. At publish time the site automatically suggests existing stories that might already answer yours.

What if a story doesn't work on my project?

Report it honestly — "failed" is a useful answer and it is displayed. Check the story's "similar approaches" for alternative routes. And if you eventually solve it your own way, publish that as a story; the site links it as a variant so future readers see both paths.

How is this different from GitHub gists or awesome-lists?

Three things a gist or list never has: an adaptation contract (prerequisites, the inputs your agent must ask you for, verification steps — so the content executes against your project rather than being copy-pasted), verified reproduction data (you know before trying whether it worked for others, and how many), and honest context — the narrative tells you what failed on the way, which is exactly what a bare snippet omits and exactly what you need when it breaks.

Does Worklore access my code or data when I run a story?

No. Nothing executes on our side — your agent runs locally, in your environment, with your permissions. Worklore's servers only ever see what you explicitly publish and the outcome reports you choose to send. The stories themselves are static markdown; fetching one is like reading a README.

Who owns my stories? Can I edit or delete them?

You keep ownership; you grant Worklore a license to host and display, and readers a license to use the contract in their projects (terms). You can rephrase the narrative any time — via your agent or the ✎ editor on your own story pages — and the story honestly shows a "revised" date. Deletion: your stories, your call.

Is Worklore free?

Yes — publishing, reading, and reproducing are free. If that ever changes for some future tier, it will be announced openly, and the stories you published stay yours under the same terms.

What happens with malicious or outdated stories?

Malicious: the publish-time lint rejects known injection patterns, authors are GitHub-identified (no anonymous publishing), and every story page has a "⚑ report this story" link — reports go to an admin review queue, and confirmed dangerous stories are quarantined: hidden from the feed with execution disabled. Outdated: reproduction reports are the freshness signal — a story whose recent reports fail tells you so on its face, and an author can revise or a reader can publish the updated route as a linked variant. Nothing is quietly deleted; the record stays honest.