agentleFS
mrdaioffmrdaioff/baby-brain/.claude/skills/librarian/SKILL.md

librarian

Skill0 starsChanged 2 months agoMITView on GitHub

Use whenever content needs to be ingested into this repo's knowledge system — a call transcript, meeting notes, a dictation, a newsletter, podcast, article, or social post. Decides whether the content is first-party or third-party, files it accordingly, preserves attribution, and extracts reusable concepts into knowledge_base/. Use when the user says "ingest this", "process this transcript", or drops a file into intake/inbox/ — and when processing an automated ingestion issue at Tier 1.

  • Commits and pushes

21 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use sentry, builder and 7 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • OpenAISkill

    sentry

    Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry CLI; perform read-only queries using the `sentry` command.

    Also in 4 projects that use this

  • scottconverseSkill

    builder

    Builder agent for the product development pipeline. Takes a sprint contract and implements exactly what it specifies — code, tests, docs. The Builder never declares work 'done' — only 'ready for review.' Only the Evaluator can declare done.

    Also in 3 projects that use this

  • cmpnd-aiSkill

    tmux

    Instructions for using tmux to spawn multiple processes, inspect them, and capture their output. Useful for running servers or long-running tasks in the background.

    Also in 3 projects that use this

  • jaydubya818Skill

    how

    Use for runtime, ownership, layering, code-walkthrough, and placement questions.

    Also in 3 projects that use this

  • MicrosoftSkill

    bro

    Re-explain the previous assistant message in a much simpler way, for when the reply made you go 'bro what'. Use /bro to get a simpler version of the last answer in Plain Language + Chicago Manual of Style, with diagrams where they help.

    Also in 3 projects that use this

  • NVIDIASkill

    github

    Interact with GitHub using the gh CLI restricted to REST API only (no GraphQL). Use when the user wants to work with GitHub issues, pull requests, repos, releases, or Actions — especially in sandboxed environments where the GraphQL endpoint may be blocked. Trigger keywords - github, gh, pull request, PR, github issue, github actions, workflow, release, gh api.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 7 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read identity in _system/config.yml before anything else.

    line 19
  2. Distinctive:

    Never record as the owner's own: something said *to* them, their agreement with someone else's point, or their paraphrase of another …

    line 85
  3. Very specific:

    Not everything deserves a knowledge_base/ entry.

    line 103
  4. Distinctive:

    Check for an existing folder first — a near-miss slug is worse than no folder.

    line 131
  5. Very specific:

    If the content describes a concrete offer — a scoped deliverable, a proposal, a price, a pitch, even an idea with no client attached — it …

    line 135
  6. Distinctive:

    Every contributor named in frontmatter

    line 209
  7. Distinctive:

    Merging two people's version of the same idea: When the owner and an external author independently land on the same insight, keep both …

    line 230
  8. Distinctive:

    Source amnesia: If you cannot say where a claim came from, it is not ready to file.

    line 236
  9. Distinctive:

    Do the work above: classify, file, attribute, extract.

    line 248
  10. Distinctive:

    Never leave a branch pushed without opening a PR.

    line 259

“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “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

The Librarian

You are filing content into a knowledge system that depends, completely, on one distinction: did this come from the owner, or from someone else?

Get that wrong and everything downstream degrades. A newsletter filed as first-party becomes something the owner "believes". A call the owner ran, filed as external, drops out of their own record. Neither failure announces itself — you find out months later, when something gets quoted in the owner's voice that was never theirs.

So: classify first, file second, extract third. In that order, every time.


Step 1 — Classify

Read identity in _system/config.yml before anything else. Three fields decide this:

FieldWhat it decides
aliasesEvery way the owner's name appears in a transcript. A speaker label matching any of these means first-party.
teammatesColleagues whose work is still first-party to this organisation, even when the owner was not on the call.
bucketsWhich commercial identity the work sits under, if the owner runs more than one.

Then:

Does a speaker label match identity.aliases, or is it "Me" / "I"?
├─ YES ──────────────────────► FIRST-PARTY → brand/artifacts/
│
├─ NO, but the author or primary speaker is in identity.teammates
│                     ───────► FIRST-PARTY → brand/artifacts/
│
└─ NO to both ───────────────► THIRD-PARTY → library/<type>/

The teammate case is the one people get wrong. A colleague's client discovery call, and an internal standup the owner missed, are both this organisation's own work product. Neither is something the owner consumed from outside. The question is never "did the owner speak" — it is "is this ours".

If a speaker is obviously the owner but is not in aliases, add them to the config and say so. Recorders mangle names, clients use nicknames, accents get dropped. Every miss silently reclassifies the owner's own work as somebody else's, and this is the most common way the system rots.


Step 2 — File it

First-party → brand/artifacts/

Filename: YYYY-MM-DD_HHmmss_Topic_Name.md. If only a date is recoverable, a date-only name is fine — do not invent a timestamp, and omit the time: field rather than guessing one.

If the source is obviously partial — it claims an hour and contains two hundred words, or the recording clearly cuts off — file what you have and say so in the artifact. Do not pad it, and do not refuse to file it. A flagged excerpt is useful; an unflagged one gets quoted later as though it were the whole conversation.

A full transcript, if you have one, goes to brand/transcripts/ under the same stem, and the two link to each other. One-way links rot; make both.

Frontmatter: the standard fields, plus — when a teammate rather than the owner was speaking — context: <bucket-id> from _system/config.yml (omit entirely if buckets are disabled) and client: <slug> matching that client's folder name exactly, since that field is what links the call to its project. Omit client for internal meetings.

Third-party → library/<type>/

newsletters/, podcasts/, videos/, social/, articles/.

Filename: YYYY-MM-DD_Title_Of_The_Piece.md, dated by publication rather than by when you read it. No time component — external work rarely has one, and invented precision is worse than none.

Frontmatter must carry the real source: author, url, date, and where you found it. An entry here without attribution is worse than no entry — sooner or later it gets quoted as though it were the owner's.


Step 3 — Attribute

Extract value; credit whoever actually produced it. That applies to hosts as much as guests, to the quiet participant as much as the loud one, and to the owner as much as anyone else.

How much did the owner actually contribute?

Estimate their share of a first-party call, because it changes what you may claim as theirs:

ShareTreat asWhat may be recorded as the owner's
Under 5%Passive sessionOnly what they explicitly said. Flag the file as passive.
5–20%Light contributionSpecific decisions and frameworks they stated. Nothing inferred.
Over 20%Active contributionTheir thinking, freely.

A passive session is still worth ingesting. Someone else may have said something excellent — extract it, attributed to them by name. The threshold governs what counts as the owner's thinking, not what is worth keeping.

Never record as the owner's own: something said to them, their agreement with someone else's point, or their paraphrase of another person's idea. Each of those belongs to the other person.

By source type

Calls. Note key moments with timestamps — [14:35] a decision, [14:50] a framework — and reference them from the artifact, so a claim can be traced back to the moment it was made.

Podcasts and interviews. List every contributor in contributors:. Credit by name: "the guest's framework", "the host argued". Where both developed a point, credit both. Skip passing mentions and bare yes/no answers.

Newsletters and articles. Establish first whether the author is originating or reporting. If they are summarising someone else's work, cite that person and link the original — the author gets credit for their framing, not for the underlying idea. Their own frameworks, research, analysis, and synthesis are theirs.

Social and video. Identify the creator. If they are discussing someone else's work, cite that person too. If it is a repost with no added commentary, go find the original and file that instead.

The rule underneath all of it: credit the person who actually said or wrote it. For the owner's own content, record only what they genuinely contributed — not what they sat and listened to.


Step 4 — Extract concepts

Not everything deserves a knowledge_base/ entry. Extract when the idea is:

  • a repeatable framework, methodology, or insight — something reusable
  • a validation or contradiction of an existing entry
  • genuinely explained, not just name-dropped
  • something you expect to reference again

Summarise instead, and create no entry, when it is specific to one company, near-duplicate of something already there, tangential, vague, or encountered only second-hand. In that last case, link the original rather than the summary.

One or two good concepts per source beats ten thin ones. Concept sprawl makes the base unusable faster than having too little in it.

New entries start at status: emergent, always — validated is earned through use, not asserted at creation. See the knowledge-base-governance skill. Link each entry to at least two related concepts with [[wiki-links]]; an orphan node is one nobody finds again. A link to a concept that does not exist yet is fine — it marks something worth writing.

Start from .agents/templates/knowledge_base_node_template.md.

Also ask: does this content imply a client engagement?

A kickoff call, a scoping conversation, a discovery call, a signed SOW — ingesting it is only half the job. If the content is about a client, that client needs a folder, a registry entry so future calls with them route automatically, and a place for the commitments in this artifact to land.

Follow .agents/skills/project-creation/SKILL.md when that applies. Filing the artifact and stopping is the most common way this system loses a client: the call is in brand/artifacts/ and looks handled, while nothing about the engagement exists anywhere, and the next call with the same client does not route either.

Check for an existing folder first — a near-miss slug is worse than no folder.

Also ask: is this a sellable service?

If the content describes a concrete offer — a scoped deliverable, a proposal, a price, a pitch, even an idea with no client attached — it belongs in services/ as well.

This is a different question from the concept one. knowledge_base/ holds the theory (why a pricing model works); services/ holds the menu item (what it is, what it costs, who has bought it). Follow .agents/skills/services-catalog/SKILL.md.

Skip it for pure market theory or positioning philosophy with no offer attached, and for internal tooling with no path to being sold.


Artifact structure

First-party artifact (brand/artifacts/):

  1. The owner's own contribution — decisions, frameworks, stances, problems named, hypotheses, with timestamps
  2. External context — what others contributed, each credited by name
  3. How this advances the work — why it mattered
  4. Key insights — the short summary
  5. Commitments and open items — who owes what, by when
  6. Concepts for knowledge_base — what you extracted, with links

Section 5 is not decorative: it is copied verbatim into the project's open-items.md. Record each owner exactly as stated, including commitments belonging to other people.

Transcript (brand/transcripts/): the full text, linked back to its artifact.

Third-party (library/<type>/): valuable insights with attribution / secondary context / how it relates to the owner's work / key insights / concepts extracted.


Frontmatter by type

First-party artifact

type: call|meeting|note|dictation
source: <recorder or "personal">
date: YYYY-MM-DD
time: HHmmss                # omit if no timestamp is recoverable
tags: [<topic>, <topic>]
speaking_percentage: <estimate>
status: raw
transcript_link: "[[brand/transcripts/...]]"
context: <bucket-id>        # only if buckets are enabled
client: <slug>              # only if a named client is involved

Transcript

type: transcript
source: <recorder or "personal">
date: YYYY-MM-DD
time: HHmmss
artifact_link: "[[brand/artifacts/...]]"

Third-party

type: newsletter|podcast|article|social|video
source: <publication>
date: YYYY-MM-DD
author: <primary author or creator>
contributors: [<host>, <guest>]   # podcasts and multi-author pieces
url: <link>

Timestamps are [HH:MM] or [HH:MM:SS] — used to mark speaker turns in a transcript, key moments in an artifact, and where a concept was discussed.


Before you call it filed

  • Classified against identity, not assumed
  • Routed to brand/ or library/ accordingly
  • Filename format correct
  • Every contributor named in frontmatter
  • Artifact and transcript link to each other
  • Speaking share estimated, passive session flagged if under 5%
  • Attribution accurate — each insight credited to whoever produced it
  • Extraction decisions made on value, not volume
  • New concepts linked to at least two others
  • At Tier 1: Fixes #<issue-number> in the PR body

Auditing a backlog: do not trust the folder a file sits in. Other processes drop files into intake/processed/, so its contents prove nothing about whether the librarian protocol ever ran on them. A file can sit there with no matching brand/ or library/ entry at all.

To audit properly, work the other direction: for each file in intake/, confirm the artifact it should have produced actually exists. And re-fetch origin/main first — a stale local checkout undercounts, and the librarian retitles files during ingestion, so match on the timestamp prefix or the source frontmatter rather than the original filename.


Anti-patterns

  • Attribution collapse. Two people's contributions blurred into one voice — or worse, someone else's thinking recorded as the owner's.
  • Assuming third-party. The default is not "external". Classify against the config; do not skip to a conclusion because a transcript looks unfamiliar.
  • Discarding a passive session. Low participation limits what counts as the owner's. It says nothing about whether the content is valuable.
  • Filtering by role. A host's aside can be worth more than the guest's headline point.
  • Concept sprawl. Ten concepts out of one article means none of them were worth extracting.
  • Merging two people's version of the same idea. When the owner and an external author independently land on the same insight, keep both entries and link them. Merging is attribution collapse wearing a tidiness costume — afterwards you cannot tell whose idea it was, which is the one thing this system exists to preserve.
  • Orphan nodes. No [[links]], no discovery.
  • Status inflation. Everything starts emergent.
  • Source amnesia. If you cannot say where a claim came from, it is not ready to file.
  • Broken cross-links. Artifact and transcript must each be findable from the other.

Tier 1: processing an ingestion issue

If the hosted pipeline is not installed — check _system/install.yml — none of this applies. Delete this section.

An ingestion issue arrives labelled ingestion, with a body beginning @claude Please ingest this content using the librarian protocol.

  1. Work on a branch. One issue, one branch, one PR — never batch several transcripts into one PR.
  2. Do the work above: classify, file, attribute, extract.
  3. Open a PR whose body contains Fixes #<issue-number>.
gh pr create --base main \
  --title "ingest: <filename>" \
  --body "Fixes #<issue-number>"

That Fixes line is load-bearing. Without it nothing auto-merges and the issue never closes, so the file sits in intake/inbox/ looking unprocessed. Find the number at the bottom of the issue body under **OFFICIAL ISSUE REFERENCE:** Ref: #<number>.

Never leave a branch pushed without opening a PR. Auto-merge triggers on the PR, not the branch, and a stranded branch is invisible until somebody audits for it.

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.