agentleFS
koloskuskoloskus/jotbook/skills/jotbook-pencil-review/SKILL.md

jotbook-pencil-review

Skill0 starsChanged 5 months agoMITView on GitHub

Review the pencil backlog and decide which provisional drafts to ink, drop, revise, edit, or keep.

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 4 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

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

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

    Read .claude/jotbook.local.md if present.

    line 12
  2. Very specific:

    If pencils_dir doesn't exist or contains no pencils, report that in one line and stop.

    line 19
  3. Very specific:

    Read the metadata block — YAML frontmatter for .md pencils, the top HTML comment for .html pencils.

    line 27
  4. Very specific:

    Check that each entry in from_jots: still resolves to a real file in jots_dir.

    line 33
  5. Distinctive:

    Ask the user in plain language.

    line 69
  6. Distinctive:

    Default to keeping source jots.

    line 83
  7. Distinctive:

    After applying, give a one-line summary:

    line 91
  8. Distinctive:

    Don't promote, drop, or regenerate without explicit confirmation.

    line 101
  9. Very specific:

    Don't read source files referenced by sources: during review — the pencil body is enough to evaluate.

    line 102
  10. Very specific:

    Don't propose drafting new pencils — that's /jot pencil <slug>.

    line 103
  11. Very specific:

    Don't proceed if pencils_dir is empty — report and stop.

    line 104
  12. Very specific:

    Don't silently invoke jotbook-ink or jotbook-pencil for an action the user hasn't explicitly marked.

    line 105

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Review the pencil backlog

The user is reviewing the pencils (provisional long-form drafts) to decide which are worth promoting to inked entries, which need a revise pass, and which should be dropped. Your job is to surface and recommend — never delete, promote, or regenerate unilaterally. Every action needs explicit confirmation.

Resolve configuration

Read .claude/jotbook.local.md if present. From its frontmatter, extract:

fielddefaultmeaning
pencils_dirdocs/jotbook/_pencils/where pencils live
jots_dirdocs/jotbook/_jots/needed to verify source-jot existence

If pencils_dir doesn't exist or contains no pencils, report that in one line and stop.

Procedure

1. Inventory

List every *.md and *.html file under pencils_dir (excluding any README.md). For each:

  • Read the metadata block — YAML frontmatter for .md pencils, the top HTML comment for .html pencils. Extract:
    • status (should be pencil — flag anything else as suspicious)
    • drafted: date
    • revised: date (if present)
    • from_jots: list
  • Compute age as today − (most recent of revised, drafted).
  • Check that each entry in from_jots: still resolves to a real file in jots_dir. Note any missing source jots — the pencil can still be promoted, but its source-jot cleanup will be partial.
  • Record the format (md or html).

Sort by age, oldest first.

2. Present

Output a compact, scannable summary. Don't over-format — the user is making decisions from this view.

Suggested shape:

Pencils (N total):

  ▸ 2026-05-12  cache-eviction-policy        (10d)  md
    From jots: 2026-05-02-cache-eviction-policy

  ▸ 2026-05-15  feature-flag-system          (7d)   html
    From jots: 2026-05-04-flag-rollout, 2026-05-05-flag-telemetry
    Revised:   2026-05-18

  ▸ 2026-05-18  webhook-retry-semantics      (4d)   md
    From jots: 2026-05-10-webhook-retry-semantics  [MISSING]

Recommendations:
  • cache-eviction-policy: ready to ink — concrete, sources still present,
    no revise history.
  • feature-flag-system: ink or keep — recent revise suggests it's settled.
  • webhook-retry-semantics: source jot is gone; still promotable but
    flag this to the user before inking.

Lead with the inventory; put your recommendations at the end. Keep the whole thing scannable — short lines, no walls of prose.

3. Solicit decisions

Ask the user in plain language. Don't present a numbered menu — let them respond free-form. Mention all five available actions so the surface is visible:

Decisions? You can say things like "ink cache-eviction-policy", "drop feature-flag-system", "revise feature-flag-system — focus on rollout only", "edit webhook-retry-semantics" (no regen, just give me the path), or "keep everything for now".

4. Apply

For each decided action:

  • Ink <slug> — hand off to jotbook-ink with the slug. The ink skill detects the pencil's existence and runs its Promotion path (skipping gather/plan/render, swapping pencil frontmatter for entry-appropriate frontmatter per output_format, writing to entries_dir, updating cross-links into related entries, deleting the pencil + source jot(s)). Confirm with the user before running if you noticed missing source jots in the inventory.
  • Drop <slug> — delete the pencil file. Before deleting, ask one question:

    "Drop pencil <slug>. Source jot(s) (<list>) can stay (default) so you can redraft later, or be deleted alongside the pencil. Which?"

    Default to keeping source jots. If the user explicitly says delete-all, also remove the source jots.

  • Revise <slug> — <notes> — invoke jotbook-pencil with the slug and pass the user's notes to its revise sub-procedure. The pencil skill applies the notes to the existing pencil in place and bumps revised: to today. If the user said revise without notes, ask once for the notes before proceeding.
  • Edit <slug> — no-op. Surface the file path so the user can hand-edit it. Mention they can re-run /jot review pencils once they're done.
  • Keep — no-op for now.

After applying, give a one-line summary:

Inked N, dropped M, revised R, edited E, kept K. Source jots deleted: <list>.

Omit the "Source jots deleted" tail if no source jots were deleted.

What NOT to do

  • Don't promote, drop, or regenerate without explicit confirmation.
  • Don't read source files referenced by sources: during review — the pencil body is enough to evaluate. Save deep reading for the user (or for ink time).
  • Don't propose drafting new pencils — that's /jot pencil <slug>. This skill only acts on existing pencils.
  • Don't proceed if pencils_dir is empty — report and stop.
  • Don't silently invoke jotbook-ink or jotbook-pencil for an action the user hasn't explicitly marked.

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.