agentleFS
hranesshraness/personal-monorepo-template/.agents/skills/percolate-reading/SKILL.md

percolate-reading

Skill4 starsChanged 49 days agoMITView on GitHub

Review saved web captures or maintained quote notes in this repository's Markdown knowledge base, turn selected sources into evidence-backed reading digests or complete reading notes, and project only explicitly published notes into the personal website. Use when triaging captured sources, percolating something read, preserving reviewed quotations, publishing a reading note, checking the reading inbox, or regenerating the public Reading collection and Atom feed.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 6 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    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:

    Only a maintained note at kb/notes/reading/<slug>.md with reading.status: published enters the public registry.

    line 14
  2. Distinctive:

    Do not publish a private capture merely because its sanitizer removed obvious secrets.

    line 17
  3. Distinctive:

    Read references/entry-format.md before creating or changing a reading note.

    line 19
  4. Very specific:

    Use $query-kb to inspect a candidate capture, its manifest, related notes, and relevant provenance.

    line 32
  5. Very specific:

    Use a digest for a public web source when a concise gist, three to five useful ideas, and up to four short verified quotations are the …

    line 36
  6. Very specific:

    Use a note when the complete reviewed passage is the public object.

    line 38
  7. Very specific:

    Keep new notes in draft until every public field, quotation, date, author, source URL, evidence relation, privacy boundary, and …

    line 40
  8. Distinctive:

    Read the entire relevant capture or evidence note.

    line 44
  9. Distinctive:

    Verify author, publication, and date metadata against the saved evidence.

    line 46
  10. Distinctive:

    Write the maintained note exactly to the selected schema.

    line 47
  11. Distinctive:

    Keep private vault paths, acquisition details, warnings, evidence IDs, and review-only flags out of public prose.

    line 50
  12. Very specific:

    When the note is ready, set reading.status: published, then regenerate:

    line 60
  13. Very specific:

    Run bun run check before handoff.

    line 71

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

Percolate Reading

Move reviewed knowledge from the private vault to the public reading surface without making the website depend on the vault.

Boundary

  • Markdown and Git in kb/ are the editorial authority.
  • A capture is evidence, not permission to publish.
  • Only a maintained note at kb/notes/reading/<slug>.md with reading.status: published enters the public registry.
  • The projector is local, deterministic, and network-silent.
  • Production imports personal-website/app/reading/entries.generated.ts; it never reads kb/, capture manifests, cookies, browser state, or authenticated material.
  • Do not publish a private capture merely because its sanitizer removed obvious secrets. Screenshots and prose can still contain private information.

Read references/entry-format.md before creating or changing a reading note.

Inspect the inbox

List manifest-backed web captures that have no related reading note:

bun run reading:inbox
bun run reading:inbox --json

The inbox is advisory and read-only. Partial captures, private acquisition methods, warnings, and non-publishable capture states are reported as review signals. Do not convert them automatically.

Use $query-kb to inspect a candidate capture, its manifest, related notes, and relevant provenance. Re-capture with $save-url-kb or $save-pdf-kb when the evidence is incomplete rather than filling gaps from memory.

Choose a form

Use a digest for a public web source when a concise gist, three to five useful ideas, and up to four short verified quotations are the public object.

Use a note when the complete reviewed passage is the public object. Complete notes require reviewed public source metadata, a confined evidence note, a precise evidence locator, full_text_reviewed: true, and an explicit republication basis before publication.

Keep new notes in draft until every public field, quotation, date, author, source URL, evidence relation, privacy boundary, and publication-rights claim has been reviewed.

Write from evidence

  1. Read the entire relevant capture or evidence note. Preserve uncertainty and capture warnings.
  2. Confirm the canonical HTTPS source URL and remove tracking parameters.
  3. Verify author, publication, and date metadata against the saved evidence. Do not invent missing precision.
  4. Write the maintained note exactly to the selected schema.
  5. For digests, verify every quote occurs verbatim in a distinct passage of the captured text. Each quote is at most 25 words; all quotes together are at most 100 words.
  6. For complete notes, confirm transcription, formatting, privacy, source accuracy, evidence location, and republication basis. Review flags record editorial work; they do not create rights.
  7. Keep private vault paths, acquisition details, warnings, evidence IDs, and review-only flags out of public prose.

Validate and publish

Validate drafts and published notes without writing:

bun run reading:check

When the note is ready, set reading.status: published, then regenerate:

bun run reading:generate
bun run reading:check
bun run kb:refresh
bun run kb:check

Review the generated diff. It should contain only public fields: slug, title, dates, reviewed source metadata, and the selected digest or complete-note content.

Run bun run check before handoff. The application tests cover reading routes, Atom serialization, bookshelf data, SEO metadata, and the generated-file boundary.

Existing entries

Edit the maintained KB note, never entries.generated.ts by hand. Re-run generation and review the public diff. To unpublish an entry, change its status to draft and regenerate; do not delete the evidence solely to remove the public projection.

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.