Agent skill

Capture Knowledge

by adamayoung in adamayoung/TMDb

Records non-obvious lessons from a finished task, such as gotchas, API quirks and design decisions, into a project's knowledge folder before a pull request opens.

Apache-2.0Auto-check passedDevelopment

Install Capture Knowledge

skills CLI
$ npx skills add adamayoung/TMDb --skill capture-knowledge -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install adamayoung/TMDb capture-knowledge --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/adamayoung/TMDb.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/capture-knowledge .claude/skills/capture-knowledge && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
capture-knowledge
GitHub stars
178
Token cost
~2.3k tokens
SKILL.md length
1,316 words
Files
1
Skills in repo
18
Repo updated
First seen
Licence
Apache-2.0

At a glance

Records non-obvious lessons from a finished task, such as gotchas, API quirks and design decisions, into a project's knowledge folder before a pull request opens.

  • Works in 7 steps: Start from the candidates list, if one… → Filter against "What NOT to capture".… → Check for duplicates — skim the relevant… → …
  • Finishing a task just before opening a pull request
  • SKILL.md covers What to capture (be selective), What NOT to capture, When an entry records a count,… and Steps, plus 1 more section
  • Calls make and git

What it does

Before a pull request, the agent folds what it just learned into the committed knowledge/ directory so a later session or contributor does not have to rediscover it. Gotchas and anything that needed a web search or doc lookup go in knowledge/gotchas.md, live API behavior goes in knowledge/tmdb-api-notes.md, and design decisions become numbered ADRs in knowledge/decisions/ with a row added to the index there.

A fix rejected or deferred because it would be a breaking change goes into knowledge/next-major.md, with its status line checked against the git tags. The skill is selective: it skips anything already in the code, CLAUDE.md, the docs or git history, and treats a learning that implies work as an issue to file rather than a note. Inside the /deliver flow it runs automatically before the PR.

When your agent uses it

  • Finishing a task just before opening a pull request
  • Recording a gotcha that took a web search or doc lookup to resolve
  • Writing an ADR for a non-obvious design choice and its rationale
  • Noting an undocumented API response field or enum value

Example prompts

  • “Capture what we learned about the nullable runtime field in the knowledge base.”
  • “Write an ADR explaining why we chose a struct over a class for the TV model.”
  • “Before I open the PR, record any gotchas from today's work.”

Requirements

  • A repository with a knowledge/ folder and a decisions/0000-template.md file

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

  1. Start from the candidates list, if one exists. If the caller passed a
  2. Filter against "What NOT to capture". Drop the rest.
  3. Check for duplicates — skim the relevant knowledge/ file; update an
  4. Write each entry in the right file
  5. **Retire what the diff invalidates — sweep by citation, not by
  6. Keep it tidy — blank lines around headings/lists/code fences, a language
  7. Update knowledge/README.md only if you added a new file or category (the

What it can do on your machine

Read from SKILL.md and the folder at commit a3f1311. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • make
    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Capture Knowledge loads about 2.3k tokens when it runs. Until then it costs about 113 tokens; SKILL.md has 1,316 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~113
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from adamayoung/TMDb at commit a3f1311, republished under its Apache-2.0 licence (© adamayoung). 1,316 words, ~2,346 tokens.

Download SKILL.mdSave it as .claude/skills/capture-knowledge/SKILL.md (or your agent's skills folder).
name
capture-knowledge
description
Capture durable, project-specific learnings from the work just done into the knowledge/ base — gotchas, implementation quirks, things looked up or web-searched, live-API behaviours, and design decisions (as ADRs). Use before opening a PR (it runs automatically in /deliver), or any time you've learned something worth remembering. Records only non-obvious, reusable facts; skips anything already in the repo, CLAUDE.md, or git history.

Capture Knowledge

Fold what you just learned into the committed knowledge base at knowledge/, so a future session (or contributor) doesn't have to re-learn or re-discover it. Run this before a PR — in /deliver it runs automatically pre-PR, so the notes land in the same PR as the change.

What to capture (be selective)

Record only durable, project-specific, non-obvious facts — the test is "would a future me waste time without this?":

  • Gotchas / quirks → knowledge/gotchas.md — a trap you hit, a tooling surprise, anything that needed a web search or doc lookup to resolve.
  • Live-API behaviours → knowledge/tmdb-api-notes.md — a nullable/absent field, an undocumented response shape, an enum value the docs omit.
  • Design decisions → a new ADR in knowledge/decisions/ (next number — take it from decisions/README.md's index, not a directory listing), using decisions/0000-template.md. Any non-obvious choice and its rationale — why this approach over the alternatives. Add the new row to that index.
  • Deferred breaking changes → knowledge/next-major.md — any fix rejected or deferred because it is breaking. The skill-improvement log remembers the "no"; this file is what makes the deferred "yes" resurface at the next major. Reconcile its status line whenever you add an entry: it states which major window is open, and an entry filed against a window that already shipped is invisible at exactly the moment it should fire. A window is open until the version is tagged — an unreleased CHANGELOG section is not a release (git tag --list | sort -V | tail -1).

What NOT to capture

Mirror the discipline of a good memory — don't record:

  • Anything already in the code, CLAUDE.md, the topic docs under .claude/docs/, the DocC docs, or git history.
  • Facts that only mattered to this one task and won't recur.
  • Restatements of the obvious. If asked to record something obvious, capture the non-obvious part (what surprised you) or skip it.

Quality over volume: a few high-signal entries beat a long dump.

A learning that implies work is not a knowledge entry. knowledge/ records what is true; an issue records what should change. "The decoder drops tv rows" is not a gotcha to remember, it is a defect to file — writing it here instead buries it in a file nobody greps until they hit the same wall. When a candidate is really a task, file it per .github/ISSUE_FILING.md and record only the durable half here, if any survives. The two are not exclusive: a live-API quirk often earns a tmdb-api-notes.md line and an issue for the code that mishandles it — cite the issue number from the entry so they stay tied.

When an entry records a count, ask what enforces it

If a candidate entry states a known-remaining defect count — "54 sites still do X", "3 models still decode Y unsafely" — stop and ask the follow-up: "what fails if that number changes?" A number in a markdown file is a promise with nothing behind it; it silently goes stale as sites are fixed or regressed, and the two cancel out.

Prefer a committed check with an explicit set, not a count (so a fix and a regression can't cancel, and an empty scan can't pass), wired into both make lint and CI — no workflow runs make, so one alone is invisible. Scripts/check-defaulted-witnesses.py is the worked example, and its history is the lesson: it began as an allowlist of sites still to fix, which checked only that the count went down. Once those sites were rewritten it had to also assert that each one's replacements were actually written, because every other gate is deletion-side — a missing replacement is a silent source break that passes lint, build, test and CI. Ask which direction your check runs in, and whether its green would look any different if the scan had matched nothing at all. If a guard isn't worth building, say so in the entry, so the number reads as an observation rather than an invariant.

Show full SKILL.md (675 more words)Show less

Steps

  1. Start from the candidates list, if one exists. If the caller passed a knowledge-candidates list as the argument ($ARGUMENTS below — /deliver pastes its ledger list here), use that as your input — that's the reliable source, jotted while the learnings were fresh, and it reaches you intact even if the caller's context was compacted. Otherwise, reconstruct candidates by reviewing the work just done — the diff, the dead-ends, the things you looked up, the decisions you made.

  2. Filter against "What NOT to capture". Drop the rest.

  3. Check for duplicates — skim the relevant knowledge/ file; update an existing entry rather than adding a near-duplicate.

  4. Write each entry in the right file:

    • Gotchas / API notes: a short dated subsection (### <title>), newest at the top, under the right heading. Date it with today's date.
    • Cite the PR that did the work, not the issue it came from. A bare #NNN is ambiguous — this repo's numbers interleave issues and PRs, so (#432) and (#417) look identical and only one is the change. Take the number from the branch's own PR; if it doesn't exist yet, leave a placeholder and backfill it. Name the issue only when the issue itself is the subject, and then say "issue #NNN" in words. (See knowledge/README.md → How to use it.)
    • Decisions: copy decisions/0000-template.md to decisions/NNNN-<kebab-title>.md (next free number), fill in Status / Date / Context / Decision / Consequences / Alternatives. Cross-link related ADRs.
  5. Retire what the diff invalidates — sweep by citation, not by neighbourhood. The base is a cache of current truths, not an archive (git history is the archive — see knowledge/README.md → Maintenance & retention). Staleness is usually caused by the very change you are capturing for, so find it from the diff:

    1. List the infrastructure files this change touched:

      bash
      git diff --name-only origin/main...HEAD | \
        grep -E '^(Makefile|Package\.swift|Package\.resolved|\.github/workflows/|\.claude/)'
    2. For each hit, grep all of knowledge/ (not just the file you are writing to) for entries citing that file, its targets, or its pinned values — e.g. grep -n 'Makefile\|make ci\|TEST_TARGET' knowledge/*.md, grep -n 'ci\.yml\|Xcode_[0-9]' knowledge/*.md. Test-target lists, pinned tool/Xcode versions, SWIFTCI_DOCC, scratch paths, and workflow step names are the usual casualties. If the change renames or removes a knowledge/ entry heading, also grep .claude/ and CLAUDE.md for citations of the old title — skills cite gotchas by title.

    3. Read every citing entry and reconcile it: still true → leave it; partly true → rewrite it in the present tense; no longer true → delete it. Never append an "Update:" / "Resolved in #NNN" note to a stale entry — rewrite or delete it. An entry that narrates its own history contradicts itself within weeks (this is exactly how the .docc gotcha decayed across #396–#402).

    4. Report the sweep as one line: swept: <infra files touched> → <entries rewritten/deleted | none cited>. No infra files in the diff → swept: n/a, and fall back to scanning the neighbouring entries of any knowledge file you edited.

  6. Keep it tidy — blank lines around headings/lists/code fences, a language on every fence, one # H1 per file. knowledge/** is in the make lint-markdown scope and the CI Lint Markdown job, so a malformed entry fails the gate rather than rendering wrong in silence (a raw | inside a table cell once did exactly that). Run make lint-markdown after writing. Aim for ~80-col prose; long jq/URL lines are fine — MD013 is disabled.

  7. Update knowledge/README.md only if you added a new file or category (the per-entry index inside each file is enough otherwise).

Return

Report concisely what you captured: each entry → which file (and ADR number for decisions), and note anything you deliberately skipped as not durable. If nothing met the bar, say so plainly — capturing nothing is a valid outcome. List any issues you filed for candidates that turned out to be work rather than knowledge.

Always end with the swept: line from step 5.4 — swept: <infra files> → <entries rewritten/deleted | none cited>, or swept: n/a. It is not optional prose: /deliver copies it into the retro and treats its absence as proof the retirement sweep never ran. A report without it reads as a skipped step.

Arguments: $ARGUMENTS

© adamayoung, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .claude/skills/capture-knowledge of adamayoung/TMDb.

Open the folder on GitHubat commit a3f1311

Compare with similar skills

Capture Knowledge next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Capture Knowledge compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Capture Knowledge this skilladamayoung/TMDb178—~2.3kAutomated safety check: PassApache-2.0
Obsidian WriterAtmosphere/atmosphere3.8k—~2.6kAutomated safety check: PassApache-2.0
Validate Connectorsimstudioai/sim30k—~5.7kAutomated safety check: PassApache-2.0
Adr Knowledgedykyi-roman/awesome-claude-code103—~2.4kAutomated safety check: PassMIT
Docsbrickbots/PiFinder250—~6.2kAutomated safety check: PassGPL-3.0
Rememberantonio-orionus/Arroxy389—~571Automated safety check: PassMIT

Similar skills

  • Obsidian Writer

    Atmosphere/atmosphere

    Write well-formatted notes to the atmosphere-vault Obsidian knowledge base.

    3.8k GitHub stars~2.6k tokensUpdated 2 days ago
    DevOps & CloudAuto-check passed
  • Validate Connector

    simstudioai/sim

    Validate an existing knowledge base connector against its service's API docs

    30k GitHub stars~5.7k tokensUpdated today
    DevelopmentAuto-check passed
  • Adr Knowledge

    dykyi-roman/awesome-claude-code

    Action-Domain-Responder pattern knowledge base. An agent skill from dykyi-roman/awesome-claude-code.

    103 GitHub stars~2.4k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Docs

    brickbots/PiFinder

    Author and edit PiFinder's user-facing documentation in the project's house style.

    250 GitHub stars~6.2k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Remember

    antonio-orionus/Arroxy

    Persists a durable Arroxy lesson — a gotcha, user preference, workflow rule, or design decision — to the right tracked file (project memory, AGENTS.md, CONTEXT.md, dev-docs, or an ADR) so any coding…

    389 GitHub stars~571 tokensUpdated 3 days ago
    DevelopmentAuto-check passed
  • Writes, repairs and copyedits project docs against the Google developer documentation style guide, verifying claims in the repository before stating them.

    949 GitHub stars~2k tokensUpdated 5 days ago
    DevelopmentAuto-check passed

More from adamayoung/TMDb

All 18 skills in this repo
  • Writes and maintains DocC /// comments for the public API of the TMDb Swift package, following the project's summary patterns and comment structure.

    178 GitHub stars~2.6k tokensUpdated 4 days ago
    Auto-check passed
  • Diagnoses a failing scheduled TMDb Integration run, re-runs transient failures, and fixes real API drift on its own branch with a PR, merging it only when told to.

    178 GitHub stars~2.7k tokensUpdated 4 days ago
    Auto-check passed
  • Drives an approved plan to completion test-first, deriving a Canon TDD test list, showing it before any code and stopping only when every item is written, passing and green.

    178 GitHub stars~4.5k tokensUpdated 4 days ago
    Auto-check passed
  • TMDb Backlog Triager

    adamayoung/TMDb

    Grooms the Backlog column of a GitHub project board by re-verifying each issue against current main, closing dead ones, promoting actionable ones to Ready and naming the decision the rest need.

    178 GitHub stars~5k tokensUpdated 4 days ago
    Auto-check passed
  • Canon TDD Workflow

    adamayoung/TMDb

    Has your agent build features and fix bugs in Canon TDD order: write a test list, then one failing test, make it pass, refactor, and repeat until the list is empty.

    178 GitHub stars~1.3k tokensUpdated 4 days ago
    Auto-check passed
  • Cut Release

    adamayoung/TMDb

    Cut a new TMDb release — work out the next SemVer version from the evidence, do the pre-tag housekeeping a tag would otherwise freeze in place, draft release notes, then tag and publish the GitHub…

    178 GitHub stars~3k tokensUpdated 4 days ago
    Auto-check passed

Questions about Capture Knowledge

What does Capture Knowledge do?

Records non-obvious lessons from a finished task, such as gotchas, API quirks and design decisions, into a project's knowledge folder before a pull request opens. Before a pull request, the agent folds what it just learned into the committed knowledge/ directory so a later session or contributor does not have to rediscover it.md, and design decisions become numbered ADRs in knowledge/decisions/ with a row added to the index there.

When should I use Capture Knowledge?

Capture Knowledge fits situations like: finishing a task just before opening a pull request; recording a gotcha that took a web search or doc lookup to resolve; writing an ADR for a non-obvious design choice and its rationale; noting an undocumented API response field or enum value.

How do I install Capture Knowledge in Claude Code?

Run `npx skills add adamayoung/TMDb --skill capture-knowledge -a claude-code`. Or copy the skill folder (.claude/skills/capture-knowledge in adamayoung/TMDb) into .claude/skills/capture-knowledge in your project. Claude Code loads it when a task matches its description.

How do I install Capture Knowledge in Codex?

Run `npx skills add adamayoung/TMDb --skill capture-knowledge -a codex`. Or copy the skill folder (.claude/skills/capture-knowledge in adamayoung/TMDb) into .agents/skills/capture-knowledge in your project. Codex loads it when a task matches its description.

Can I use Capture Knowledge in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add adamayoung/TMDb --skill capture-knowledge -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/capture-knowledge, .gemini/skills/capture-knowledge, .github/skills/capture-knowledge and .opencode/skills/capture-knowledge in your project.

What does Capture Knowledge need to run?

Going by SKILL.md and its folder, Capture Knowledge needs the command-line tools its instructions call (make and git). Our summary lists: A repository with a knowledge/ folder and a decisions/0000-template.md file.

Does Capture Knowledge access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Capture Knowledge safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Capture Knowledge use?

Capture Knowledge is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Capture Knowledge use?

About 2.3k tokens (SKILL.md is roughly 9.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Capture Knowledge?

Skills that share tags, products or a category with Capture Knowledge: Obsidian Writer (Atmosphere/atmosphere, 3.8k stars), Validate Connector (simstudioai/sim, 30k stars), Adr Knowledge (dykyi-roman/awesome-claude-code, 103 stars) and Docs (brickbots/PiFinder, 250 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Capture Knowledge?

adamayoung (a GitHub user) maintains it in adamayoung/TMDb, which has 178 GitHub stars. The repository holds 18 skills in this directory. The repository was last updated on October 3, 2026.

Source: adamayoung/TMDb on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.