bragdoc
Skill2 starsChanged 33 days agoMITView on GitHub
In-depth, metric-backed brag document of the user's engineering and career work (a performance-review and career record). Commands - dump, stage, probe, renovate, brag, extractor. Use whenever the user mentions achievements, brain dumps, work they did, weekly wins, updating their brag doc, an extensive resume, or summaries from coding sessions - even without saying "bragdoc".
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 5 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Every staging item and every probe transcript is kept: data/bragdoc/probes/<staging-id>.md.
- Very specific: line 24
Always write a one-line rank_rationale.
- Very specific: line 37
When T0 overrides a lower-tier value, keep the old record with superseded: "<why>".
- Distinctive: line 53
After writing: a table per batch (items, probed/raw, open gaps, conflicts), then all questions grouped by batch with conflicts first.
- Distinctive: line 66
Result: before/after metrics (latency, users, time saved, error rate, revenue), and how I know
- Distinctive: line 69
Logic gaps: call out inconsistencies, vague verbs ("helped", "worked on"), and unverifiable claims
- Very specific: line 83
no open conflicts, no needs_confirmation claims, empty open_gaps
- Very specific: line 101
Run python scripts/render.py bragdoc, which produces out/<names.short>_BragDoc.pdf (HTML fallback if PDF tooling is missing): Experience …
- Distinctive: line 102
Commit and push. End the output with:
- Very specific: line 128
Remove: internal system/service/table names, proprietary platform internals, exploitable security specifics, anything in public_constraints …
- Very specific: line 135
Never include anything in public_constraints.
- Distinctive: line 140
Never add claims not in the entry.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
bragDoc
No command given (bare /bragdoc): read COMMANDS.md and print its ## bragDoc section verbatim (heading through the line before the next ## ) in a fenced code block. Nothing else, no commit.
"An in-depth, detailed brag document of all my engineering and career work."
Pipeline: dump → staging (raw) → probe → staging (probed) → renovate → entries.jsonl → rendered PDF
data/bragdoc/entries.jsonlis the source of truth. The PDF is always rendered from it by script, never hand-written.- Facts in an entry change only through probe or my explicit correction, and always shown as a diff.
- Every staging item and every probe transcript is kept:
data/bragdoc/probes/<staging-id>.md.
Impressiveness scoring (rank_score 1–10)
Measured relative to an engineer in the same field with my tenure (career_start in data/profile.json → today). Ask: "For someone this far into their career, how cool is this?"
- 9–10: rare at this tenure (owned a system end to end at scale, a significant measurable business or perf impact, novel design)
- 7–8: clearly above peers (led a feature across services, strong metrics)
- 5–6: solid, expected of a good engineer at this level
- 1–4: routine; keep it for completeness
Always write a one-line
rank_rationale. My override wins; record it asrationale: "user override: ...".
Commands
dump (one-off; show a plan with counts and wait for my go before writing data/)
Accept text, files, or folders (brain dumps, old resumes, docs). Move originals to raw/bragdoc/<YYYYMMDD-HHMM>-<name> (images via python scripts/ingest_images.py bragdoc <paths>). Never edit originals. Single items (and other domains' handoffs) are appended with python scripts/bragdoc_stage.py add -.
Source trust tiers. Tag every extracted claim with its source file and tier, stored per item as source_claims: [{claim, value, source, tier}]:
- T0: my explicit statements in chat (
source: "user"). Always wins. - T1: my own notes (newest first).
- T2: resumes I approved (newest first; older versions mostly superseded). Claims that appear only in resumes are true and defensible; stage them for depth, never mark them unverified.
- T3: AI-generated text (summaries, other assistants' dumps). Anything only in T3, or marked "assumed", "inferred" or "WEAK", gets
needs_confirmation: trueand must be confirmed in probe before it reaches an entry. - From T3, extract only facts (numbers, names, events, technologies, outcomes), not reworded purpose statements. A T3 claim restating a T0–T2 fact joins that claim's group, so it isn't flagged.
- When T0 overrides a lower-tier value, keep the old record with
superseded: "<why>".
Deduplication. One staging item per distinct achievement; merge every mention across files, keeping all variants in source_claims. Dedupe against existing staging.jsonl and entries.jsonl too.
Batches. One project per batch: b-<date>-<project-slug>. Large projects split by sub-area (e.g. a platform split into access control, report pipeline, ingestion, …). Each item also carries project and employer.
Conflicts. When non-T0 sources disagree, add conflicts: [{field, values: [{value, source, tier}], status, ...}]. Open conflicts get a question in questions.jsonl (topic: "conflict") citing each value and its source; T0- or script-settled ones are status: "resolved" with a resolution. Never ask about anything a script can compute (ratios, percentages): run the script and store the result.
Pre-probed fast path. Fill probe fields from sources for every item (only T0–T2 facts, never T3-only ones). An item goes straight to status: "probed" only if it meets the completeness criterion below and has no open conflicts, no needs_confirmation claims and a known kind. Otherwise status: "raw" with open_gaps listing exactly what's missing, so probe asks only that. For each fast-path item, write probes/<id>.md listing the claims each field came from, and add a confidentiality question (topic: "confidentiality"): "anything here not OK to say publicly?" (the fast path skips the probe's own question).
Everything goes in the bragDoc. Achievements, including community, teaching, leadership and competitions, go through staging (non-engineering ones: kind: "community", category "Community & Leadership" at renovate). Other material goes to its own file (schemas in scripts/schemas.md):
- skills →
skills.json(level only in my own words; evidence viaevidence_staging_idsuntil renovate) - education →
education.json - employment history →
employment.json(employer, role, start, end, source; company awards and team size ascontext, never as my achievement; no salaries, addresses or phone numbers).contextis internal: only the internal bragDoc shows it. Every resume and the public PDF use the user-approvedpublic_summary(one sentence under the role) andpublic_context(lines) instead - unfinished work →
in_progress.jsonl(promote to a staging item when completed)
After writing: a table per batch (items, probed/raw, open gaps, conflicts), then all questions grouped by batch with conflicts first. Validate, commit, push.
stage (one-off)
Table of staging items: id, batch, one-line summary, status, open gaps. Group by batch. Exclude merged unless asked.
probe (back and forth; ends on /end or auto when the item has no open gaps)
Take one raw item or batch (I can name one; default is the oldest raw batch).
Before asking anything: read the item's open_gaps, conflicts and source_claims, then look up its project in data/bragdoc/probe_bank.md (if present). Skip every bank question the item's data already answers. Order: open conflicts (with their questions in questions.jsonl), then needs_confirmation claims, then the other gaps, then bank questions. When I answer a conflict or confirm a claim, record my answer as a T0 claim, resolve the conflict or clear the flag, and mark the question answered.
Grill like a senior engineer reviewing me for the next level:
- Problem: what was broken or missing, and who felt it
- Action: what I did versus the team, and the decisions and trade-offs I made
- Result: before/after metrics (latency, users, time saved, error rate, revenue), and how I know
- Scope: systems, scale, and stakeholders touched
- Stack: specific technologies
- Logic gaps: call out inconsistencies, vague verbs ("helped", "worked on"), and unverifiable claims
Near the end of each item, ask naturally as part of the conversation (not as a form):
- Kind: is this work for an employer/client, a personal project, a product (has users / a landing page), an open-source contribution, or community (teaching, volunteering, competitions, clubs)?
- Links (non-work only): repo, live URL, landing page, demo, docs.
- Confidentiality: "Is anything here not OK to say publicly: client names, internal numbers, system names, unreleased features?"
One question at a time. Estimated metrics are allowed only if labelled as estimates with the method stated.
Completeness criterion ("probed"), enforced by validate.py:
problem,action,result,my_roleandstackfilled- at least one scale metric (users, records, requests/day, team size) and one impact metric (% improvement, time saved, issues resolved), each tagged
type: "scale" | "impact"inprobe.metrics - an ownership signal in
my_role/action(led, designed, owned, independently built) - no passive verbs (worked on, helped, assisted, was responsible for)
- no open conflicts, no
needs_confirmationclaims, emptyopen_gaps - Answered without data (my AS-IS, or "don't know" to a metric or the stack):
probe.waived={fields: [scale|impact|stack|problem], source: "user, <date> (<answers file>)", reason}exempts exactly those parts, nothing else. Only my answer waives; never fill the gap with an estimate instead
Save the transcript (these answers included, like every other answer), fill probe including kind, links, and public_constraints (if I say "nothing", store [] explicitly), set status: probed (or probing if ended early, with open_gaps listed). Commit.
renovate (one-off)
- For each
probeditem, create or merge into an entry: professional resume-style phrasing, all details kept, no redundancy. Setstatus: merged.- Carry over
kind,links,public_constraintsfrom the probe (merging items: union of constraints, merge links). Create every new entry withpython scripts/bragdoc_public.py add-entry '<json>': it assigns the id,published_hash: nulland the standing visibility default (data/runway/config.json→visibility_default, the user's own rule; the template ships with every new entry private): for example public, unless the entry is the current employer's (then private). Never setvisibilityby hand; later changes only via set-visibility on the user's word. A merge into an existing entry never changes its visibility,site_slugorpublished_hash. - Kind unknown:
workifemployeris set; otherwise add atopic: "kind"question toquestions.jsonland leave the item in staging until answered. - Carry the staging item's
employerinto the entry. Then swap staging ids for entry ids inskills.json(evidence_staging_ids→evidence_entry_ids) and ineducation.json(capstone.entry_id).
- Carry over
- Recategorize all entries into loose technical categories (e.g. Backend & APIs, Data & Databases, Cloud & DevOps, Mobile, Performance, Architecture). No timeline narrative.
kind: "community"entries (teaching, volunteering, competitions, clubs, podcast) go in "Community & Leadership", ranked within it like any category. - Re-rank within each category by
rank_score, highest first. - Show the diff summary (new, merged, re-ranked, recategorized). Write, validate.
- Public layer: everything the site needs, for EVERY entry whatever its visibility (nothing is generated at publish time):
python scripts/bragdoc_public.py stale→ for each listed entry and channel, write the text under that channel's rules (below) and save it: summaries withpython scripts/bragdoc_public.py set-summary <id> '<json>' --channel public|resume, site cards withpython scripts/bragdoc_public.py set-card <id> '<json>'({metric, context, did, result, where}with a short metric, public rules, the entry's own employer deciding which figures it may carry). The scripts stampgeneratedandsource_hashand reject anythingdisclosure_lintblocks; fix and resave. No approval step.python scripts/bragdoc_public.py finalize: setsyearon entries and staging items (period, elsedata/bragdoc/project_years.json, else a single-year tenure), cuts each missingsite_slugfrom the public headline (never changed afterwards), and lists anything still missing; repeat until it reports every entry complete. An entry with no year rule: ask for its year and add it toproject_years.json.python scripts/bragdoc_public.py missing-links --add-questionspython scripts/bragdoc_public.py pending
- Run
python scripts/render.py bragdoc, which producesout/<names.short>_BragDoc.pdf(HTML fallback if PDF tooling is missing): Experience (fromemployment.json), the ranked categories, Skills, Education, Community & Leadership, In Progress. Show the path. - Commit and push. End the output with:
Then, automatically:Public layer - N summaries generated/refreshed - N public entries pending a site update: <titles> - N non-work entries missing linkspython scripts/runway.py publish --if-pending. When any public payload changed, it ships to the site repo'scontentbranch and prints the preview URL (add it to the output); otherwise it does nothing. It never touchesmain: promote stays manual (/runway promote), the one human gate before anything goes live. Then:python scripts/profiles.py policy, and add its reminder (if any) to the output: which profile pieces are stale and why (EXTROVERTprofiles). Then:python scripts/repos.py status, and add its reminder (if any): which public repos need fresh metadata suggestions (EXTROVERTrepos).
Items not yet probed stay in staging.
Disclosure channels
Everything that leaves the bragDoc goes through one of three channels defined in data/bragdoc/disclosure_policy.json and enforced by python scripts/disclosure_lint.py --channel internal|resume|public <file>. Renders lint themselves and write nothing on failure; a failure shows the offending lines, which get fixed (usually by regenerating that entry's channel summary). Nothing ships with a lint failure.
- internal (
render.py bragdoc): only me. Full entry detail, security specifics, all contacts, cost figures. - resume (
render.py resume-extensiveand any resume built from the bragDoc): written fromresume_summary+ resume contacts (phone and the personal email; resumes always use the personal email, never the domain email). - public (the website, shipped by RUNWAY;
render.py public-resumeis its PDF, served as/<names.short>_Resume.pdf, public entries only): written frompublic_summaryandsite_card+ public contacts (the domain email, never phone or personal email). - Names (
data/profile.json→names; each channel's form is in the policy): internal renders showshort, resume rendersformalexactly as stored, the public resumepublic_full. Summaries and other public prose useshort, orpublic_fullonly where a full name is genuinely required. Never type a name into an output; an all-caps design is CSStext-transform: uppercase, never changed text. The lint flags any wrong casing of the formal name on every channel.
Public layer
Cockpit prepares public data; only RUNWAY ships it (/runway). published_hash is set only by runway.py promote, never by hand or by bragdoc.
Two channel summaries plus one site card per entry (cards follow the public rules below). Summaries share one structure (headline ≤ 12 words, summary 2–4 sentences, highlights 2–4 short bullets, stack public tech only) and the same source_hash/stale machinery. Both are generated for every entry regardless of visibility, from the entry, its probe transcript, public_constraints, and common sense.
Resume summary (resume_summary; anyone reading your resume sees it):
- Remove: internal system/service/table names, proprietary platform internals, exploitable security specifics, anything in
public_constraints(e.g. no security details tied to a named client). - Allowed: client/employer names, project/app names, generic vulnerability classes (the categories listed in the policy), engineering metrics (latency, throughput, test counts, coverage like 66/66), business scale (users, records).
- Employer money figures: relative change only, never absolute values.
Public summary (public_summary) redaction rules, always applied, even when public_constraints is empty:
- Everything the resume summary removes, plus: no vulnerability class names (keep the achievement: "hardened external document fetching", not the class name).
- Costs (the user's rule): relative cost changes (a percentage cut in hosting spend, say) from past employers', clients' or personal work are allowed; absolute amounts (currency amounts, per-month figures) never; any cost figure about the current employer never. The current employer is always the open role in
employment.json, so a job change re-tiers this automatically. - Never include anything in
public_constraints. - Client/employer and project/app names are allowed, but never alongside security details for that client. Work entries: no internal system/service names; no security architecture details or vulnerabilities; no unreleased features or roadmap.
- Business numbers (the user's rule, enforced by disclosure_lint): user counts and usage scale (users, downloads, concurrent users, records, sites) from past employers', clients' or personal work are allowed; the current employer's user, tenant and customer counts never; revenue and contract values never, for any employer. Per-entry
public_constraintsstill win. - Allowed: employer name, the problem type in generic terms, my role, public technologies, and impact as relative change ("cut p95 latency by ~60%") when the absolute numbers aren't sensitive (money figures: see above). Compute the change with
python scripts/bragdoc_public.py change <before> <after>, never in your head. - Personal projects, products, open source, community: anything I'd put in a public README is fine; still respect
public_constraints. Only personal projects, products and open source are expected to have links. - Never add claims not in the entry. Same truthfulness rules as the rest of bragDoc.
- Tone: confident, concrete, no buzzwords; readable by any engineer or reviewer.
Visibility: changes only when I explicitly say so. "make <entry> public|private" (by id or title; if ambiguous, ask which) → python scripts/bragdoc_public.py set-visibility <id> public|private, show the entry's public_summary, commit, push.
brag (one-off)
Run python scripts/render.py resume-extensive, which produces out/<names.formal>_Resume_Extensive.pdf (spaces as underscores) on the resume channel: ATS-friendly, single column, standard headings, the whole bragDoc except In Progress, written from each entry's resume_summary with resume contacts. The render lints itself; on failure, show the offending lines, fix the summaries, re-render. Show the path.
extractor (two steps: emit a prompt, then take the summary back as a dump)
Modes, one prompt per kind of source:
| Command | Prompt for |
/bragdoc extractor | session (default): the work done in the current AI pair session / repo |
/bragdoc extractor incident <date> <short description> | one incident: timeline with timestamps (first symptom, detection, diagnosis, mitigation, resolution), durations computed from the timestamps, impact, root cause, fix, prevention added, what I'd do differently |
/bragdoc extractor project | one project: what it is, owner (personal / employer / client), status and dates from git, architecture and data flow, decisions and trade-offs, evaluation, metrics, what's novel, stack, links |
/bragdoc extractor period <from> <to> <topic> | multi-month work (e.g. a quarter-long migration or a pipeline rebuilt over several iterations): phases, the problem before, what changed and why per phase, metrics then vs now (still true?), ownership, decisions, what went wrong and the fix, stack |
- Emit (one-off, writes nothing, no commit):
python scripts/extractor.py prompt <mode> [args] [--personal], shown verbatim in one fenced block, ready to paste. The script writes every prompt; never hand-write, trim or reword it. Every prompt carries: a READ-ONLY block (no file edits, no commits/pushes/branches/stashes, no migrations, builds, tests, scripts or DB queries; read files and read-only git only; answer in chat, save nothing), evidence tags on every number and claim ([measured],[from git/logs/docs],[estimate],[from my memory]), strict ownership (mine vs others'), a confidentiality block, and a closing "Notes for you" (what was left out and why, what's unverified). The confidentiality block (no code, hostnames/IPs/URLs, credentials or env values, table/service names, client names, exploitable specifics) stays unless the work clearly belongs to no employer or client; only then pass--personal. If unsure, keep it. Incident dates and period bounds are checked by the script. - Paste-back (when I paste the summary): it is a dump, so every dump rule applies (tiers, dedupe, conflicts, show the plan and wait for my go), plus:
- Source:
python scripts/extractor.py source <mode>→extractor:<mode>:<date>on every item. - Evidence: each claim keeps its tag in
source_claims[].evidence(measured|git|estimate|memory). The summary is AI-written, so claims are T3 withneeds_confirmationas usual; in probe, confirm themeasuredandgitones in one batch question. An untagged number is not stored; it becomes a question. - Overlaps first, before creating anything: for each item,
python scripts/extractor.py overlaps '<json>'(raw, project, employer, and the incident date or period bounds). Show every likely/possible overlap and ask: merge into the existing item (new claims added to it) or create a new one. Example: an incident write-up vs an existing entry that already mentions the same failed migration that month. - Incidents: recompute time to detect / mitigate / resolve with
python scripts/extractor.py durations <first_symptom> <detected|unknown> <resolved> [--mitigated <ts>](passunknownwhen there's no detection timestamp; the script then reports only the intervals the timestamps support). If the summary's numbers differ, the script's win and the mismatch becomes a question. Store the timestamps and durations as claims; never "record time" or similar. - Create with
python scripts/bragdoc_stage.py add -(status raw; the summary's gaps and its "Notes for you" unverified claims go intoopen_gaps; what it left out for confidentiality stays out). A project whose status is in progress also getspython scripts/bragdoc_stage.py add-in-progress -(kind: project,staging_id= the new item). - Validate, commit
bragdoc: extractor: <mode>: <n> items, push. Offer to probe them.
- Source:
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

