agentleFS
aalishan001aalishan001/opencockpit/.claude/skills/bragdoc/SKILL.md

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
  1. Very specific:

    Every staging item and every probe transcript is kept: data/bragdoc/probes/<staging-id>.md.

    line 16
  2. Very specific:

    Always write a one-line rank_rationale.

    line 24
  3. Very specific:

    When T0 overrides a lower-tier value, keep the old record with superseded: "<why>".

    line 37
  4. Distinctive:

    After writing: a table per batch (items, probed/raw, open gaps, conflicts), then all questions grouped by batch with conflicts first.

    line 53
  5. Distinctive:

    Result: before/after metrics (latency, users, time saved, error rate, revenue), and how I know

    line 66
  6. Distinctive:

    Logic gaps: call out inconsistencies, vague verbs ("helped", "worked on"), and unverifiable claims

    line 69
  7. Very specific:

    no open conflicts, no needs_confirmation claims, empty open_gaps

    line 83
  8. Very specific:

    Run python scripts/render.py bragdoc, which produces out/<names.short>_BragDoc.pdf (HTML fallback if PDF tooling is missing): Experience …

    line 101
  9. Distinctive:

    Commit and push. End the output with:

    line 102
  10. Very specific:

    Remove: internal system/service/table names, proprietary platform internals, exploitable security specifics, anything in public_constraints …

    line 128
  11. Very specific:

    Never include anything in public_constraints.

    line 135
  12. Distinctive:

    Never add claims not in the entry.

    line 140

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.jsonl is 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 as rationale: "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: true and 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 via evidence_staging_ids until renovate)
  • education → education.json
  • employment history → employment.json (employer, role, start, end, source; company awards and team size as context, never as my achievement; no salaries, addresses or phone numbers). context is internal: only the internal bragDoc shows it. Every resume and the public PDF use the user-approved public_summary (one sentence under the role) and public_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_role and stack filled
  • 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" in probe.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_confirmation claims, empty open_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)

  1. For each probed item, create or merge into an entry: professional resume-style phrasing, all details kept, no redundancy. Set status: merged.
    • Carry over kind, links, public_constraints from the probe (merging items: union of constraints, merge links). Create every new entry with python scripts/bragdoc_public.py add-entry '<json>': it assigns the id, published_hash: null and 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 set visibility by hand; later changes only via set-visibility on the user's word. A merge into an existing entry never changes its visibility, site_slug or published_hash.
    • Kind unknown: work if employer is set; otherwise add a topic: "kind" question to questions.jsonl and leave the item in staging until answered.
    • Carry the staging item's employer into the entry. Then swap staging ids for entry ids in skills.json (evidence_staging_ids → evidence_entry_ids) and in education.json (capstone.entry_id).
  2. 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.
  3. Re-rank within each category by rank_score, highest first.
  4. Show the diff summary (new, merged, re-ranked, recategorized). Write, validate.
  5. 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 with python scripts/bragdoc_public.py set-summary <id> '<json>' --channel public|resume, site cards with python 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 stamp generated and source_hash and reject anything disclosure_lint blocks; fix and resave. No approval step.
    • python scripts/bragdoc_public.py finalize: sets year on entries and staging items (period, else data/bragdoc/project_years.json, else a single-year tenure), cuts each missing site_slug from 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 to project_years.json.
    • python scripts/bragdoc_public.py missing-links --add-questions
    • python scripts/bragdoc_public.py pending
  6. Run python scripts/render.py bragdoc, which produces out/<names.short>_BragDoc.pdf (HTML fallback if PDF tooling is missing): Experience (from employment.json), the ranked categories, Skills, Education, Community & Leadership, In Progress. Show the path.
  7. Commit and push. End the output with:
    Public layer
    - N summaries generated/refreshed
    - N public entries pending a site update: <titles>
    - N non-work entries missing links
    Then, automatically: python scripts/runway.py publish --if-pending. When any public payload changed, it ships to the site repo's content branch and prints the preview URL (add it to the output); otherwise it does nothing. It never touches main: 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 (EXTROVERT profiles). Then: python scripts/repos.py status, and add its reminder (if any): which public repos need fresh metadata suggestions (EXTROVERT repos).

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-extensive and any resume built from the bragDoc): written from resume_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-resume is its PDF, served as /<names.short>_Resume.pdf, public entries only): written from public_summary and site_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 show short, resume renders formal exactly as stored, the public resume public_full. Summaries and other public prose use short, or public_full only where a full name is genuinely required. Never type a name into an output; an all-caps design is CSS text-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_constraints still 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:

CommandPrompt for
/bragdoc extractorsession (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 projectone 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
  1. 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.
  2. 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 with needs_confirmation as usual; in probe, confirm the measured and git ones 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>] (pass unknown when 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 into open_gaps; what it left out for confidentiality stays out). A project whose status is in progress also gets python 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.