Guides and resources for AI engineers: an agents course, five handbooks, a hands-on second-brain project and a vetted reading list.
JavaScript agent-skillsai-agentsai-engineeringclaudeclaude-codeclaude-skillsknowledge-graphknowledge-managementllmmcpobsidianpersonal-knowledge-basepkmsecond-brain
docs: agents
undefined-ui0efd6f279c3a
diff --git a/README.md b/README.mdindex 70c6626..b645d2f 100644--- a/README.md+++ b/README.md@@ -115,7 +115,7 @@ you can see exactly what is coming and open a pull request against any of it.| [Ingestion](docs/03-ingestion/README.md) | articles, video, PDFs, chat exports, voice, backfilling | **written** || [Structuring](docs/04-structuring/README.md) | page types, linking rules, schema, contradictions | **written** || [Graphs](docs/05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics | **written** |-| [Agents](docs/06-agents/README.md) | roles, schedules, hooks, guardrails | in progress |+| [Agents](docs/06-agents/README.md) | roles, schedules, hooks, guardrails | **written** || [Retrieval](docs/07-retrieval/README.md) | query patterns, search, context budget | in progress || [Outputs](docs/08-outputs/README.md) | writing, reports, publishing, learning | in progress || [Maintenance](docs/09-maintenance/README.md) | linting, review cadence, git, privacy, scaling | in progress |diff --git a/docs/06-agents/README.md b/docs/06-agents/README.mdindex 4315d03..e2c3779 100644--- a/docs/06-agents/README.md+++ b/docs/06-agents/README.md@@ -2,16 +2,23 @@Turning a one-off setup into a system that maintains itself.-## Planned+Everything up to here you could do by hand, slowly. This section is where the+vault stops depending on your discipline, which is the only reason it will still+be alive in six months.-Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.+It is also where the risk lives. An agent with write access to your notes,+running on a schedule while you sleep, is exactly as useful and exactly as+dangerous as it sounds. Read [guardrails](safety-and-guardrails.md) before you+schedule anything.-- Agent roles-- Scheduling-- Subagents and parallel work-- Hooks-- Skills and slash commands-- Guardrails+## Pages++- [Agent roles](agent-roles.md)+- [Scheduling](scheduled-maintenance.md)+- [Subagents and parallel work](subagents.md)+- [Hooks](hooks.md)+- [Skills and slash commands](skills-and-commands.md)+- [Guardrails](safety-and-guardrails.md)---diff --git a/docs/06-agents/agent-roles.md b/docs/06-agents/agent-roles.mdnew file mode 100644index 0000000..1a441f1--- /dev/null+++ b/docs/06-agents/agent-roles.md@@ -0,0 +1,72 @@+# Agent roles++One agent doing everything produces mediocre work at every job. The instructions+that make a good ingestor are not the ones that make a good reviewer, and stuffed+into one prompt they dilute each other.++Four roles cover a vault. The definitions are in+[`agents/`](../../agents/README.md).++## Ingestor++Reads `raw/`, writes wiki pages, links them, updates the index and log. Writes+more than any other role and is the one whose output quality determines+everything downstream.++Its instructions are narrow on purpose: it does not answer questions, does not+restructure existing pages beyond adding links, and does not delete. An ingestor+that reorganises while ingesting produces runs you cannot review, because content+changes and structural changes arrive mixed in the same diff.++## Linker++Finds connections between existing pages that ingestion missed.++Runs after imports and weekly. Adds links, creates nothing, rewrites nothing.+Separating it from the ingestor matters because linking well requires reading+broadly across the vault, which is a different job from reading one source+closely.++Its one rule: a link it adds must be one you would agree with on reading both+pages side by side. A linker optimising for link count degrades the graph while+appearing productive.++## Reviewer++Read-only. Produces the periodic review: what changed, where attention went,+what contradicts what, what to read next.++Read-only is not caution, it is what makes the review trustworthy. A reviewer+that can edit will fix small things as it goes, and then its report describes a+vault that no longer exists.++## Researcher++Read-only. Answers questions from the vault, cites pages, names what is missing.++Also the role you talk to most, and the one that most needs the rule about not+falling back on general knowledge. See the+[query skill](../../skills/README.md).++## Roles not worth creating++**A deleter.** Deletion should be a decision you make, executed with a record.++**A summariser.** Summaries of pages that are already summaries produce a layer+that is less true than what is under it and gets read instead of it.++**A tagger.** Tagging is a five-second judgement made during ingest with full+context. A separate pass has less context and produces worse tags.++## Handoffs++Roles communicate through the vault, not through each other. The ingestor writes+gaps into `index.md`; the linker reads them. The ingestor logs its run; the+reviewer reads the log.++That is deliberate. Files as the interface means any run is inspectable+afterwards, and a role can be replaced without touching the others.++## Next++[Scheduling](scheduled-maintenance.md)diff --git a/docs/06-agents/hooks.md b/docs/06-agents/hooks.mdnew file mode 100644index 0000000..ada833f--- /dev/null+++ b/docs/06-agents/hooks.md@@ -0,0 +1,50 @@+# Hooks++Hooks fire on events rather than on a schedule. They are the right tool for+things that must happen every time, which is exactly the set of things a prompt+instruction will eventually miss.++## Worth hooking++**Validation before a write.** Check frontmatter parses and required fields are+present. A malformed page caught at write time is a non-event; caught a month+later it is a page that has been invisible to every query since.++**Lint after a run.** Broken links appear at the moment they are created, which+is the moment there is enough context to fix them properly.++**Commit after a scheduled run.** Removes the possibility of a run that changed+forty files and left no commit.++**Notify on deletion.** Any delete, any time, surfaces. Deletions are rare enough+that a notification costs nothing and matters when it fires.++## Not worth hooking++Anything slow. A hook that runs on every file write and takes two seconds turns a+forty-page ingest into a ninety-second pause, and you will disable it.++Anything that needs judgement. Hooks are mechanical checks. A hook trying to+decide whether a page is good enough will be wrong in both directions.++## Keep them fast and quiet++A hook should complete in well under a second and print nothing when it passes.+Hooks that log on success train you to ignore hook output, which is the same as+having no hooks the day one fails.++## Failure behaviour++Decide explicitly whether a failing hook blocks the operation.++Validation hooks should block: a page that fails schema validation should not be+written. Notification hooks should not: a failed notification is not a reason to+lose the work.++The bad case is a blocking hook that fails for an unrelated reason and silently+stops your scheduled ingest for a week. Whatever blocks must be simple enough+that it only fails for the reason it exists.++## Next++[Skills and slash commands](skills-and-commands.md)diff --git a/docs/06-agents/safety-and-guardrails.md b/docs/06-agents/safety-and-guardrails.mdnew file mode 100644index 0000000..20ac33a--- /dev/null+++ b/docs/06-agents/safety-and-guardrails.md@@ -0,0 +1,79 @@+# Guardrails++The rule this whole section rests on:++**Keys, not prompts.**++Telling an agent not to do something is a preference. It is not a boundary. If+the agent technically can delete a file, empty a folder or send an email, then+one day, in a context you did not anticipate, it will.++Control what is possible at the permission level. Then the instruction in+`CLAUDE.md` is a preference sitting on top of a boundary, rather than the only+thing between your notes and a bad run.++## Scope write access++The agent needs write access to the vault. It does not need write access to your+home directory, and a scheduled task running with broad filesystem permissions is+a large blast radius for a small convenience.++Same principle for connectors: read-only wherever the option exists. A calendar+connector that can only read cannot cancel a meeting, no matter what a+misinterpreted instruction says.++## Never delete without a record++Deletion is the one operation you cannot recover from by reading a diff, because+the content is gone and only the absence remains.++Rule: no page is deleted without a line in `log.md` naming it and why. Merges+count as deletions. Applied consistently, a page that vanishes is always+traceable, and "where did that page go" stops being an unanswerable question.++## Git is the real safety net++Every guardrail above is preventive. Git is what saves you when one fails.++Commit before any run that writes at scale. Scheduled runs commit their own work.+Then a bad ingest is `git checkout .`, and a bad merge is one revert.++Read the diffs from scheduled runs occasionally, especially in the first weeks.+That is how you learn what your agent actually does at 7am, which is reliably+different from what you assumed.++## Dry runs++For anything that touches many files, run it once in report-only mode.++```+Do a dry run: list every page you would create, update or delete, and the links+you would add. Write nothing.+```++The output takes a minute to read and catches misread instructions before they+become four hundred edits.++## Watch for scope creep++Agents extend the job. Asked to ingest, an agent may also tidy an unrelated page,+fix formatting, rename something for consistency. Each is defensible; together+they mean you cannot tell what a run did without reading everything.++Instruct explicitly: do the job asked, list anything else you noticed, change+nothing else.++## What not to put in the vault++Credentials, API keys, anything you are under obligation to keep confidential,+other people's private information.++Not because the agent will leak it, but because the vault is a single file tree+that gets synced, committed, backed up and occasionally shared. Every copy is+another place that content exists. See+[privacy](../09-maintenance/privacy-and-secrets.md).++## Next++[Retrieval](../07-retrieval/README.md), for getting answers out of what all this+built.diff --git a/docs/06-agents/scheduled-maintenance.md b/docs/06-agents/scheduled-maintenance.mdnew file mode 100644index 0000000..52433a8--- /dev/null+++ b/docs/06-agents/scheduled-maintenance.md@@ -0,0 +1,79 @@+# Scheduling++Scheduled runs are what make the vault feel alive. You wake up and it has filed+what you clipped, noticed a contradiction, and left you three lines about what+changed.++They are also unattended writes to your notes, so the order matters: get the+[guardrails](safety-and-guardrails.md) right first, then schedule.++## Cadence per job++**Ingest, daily.** Overnight, on whatever accumulated in `raw/` during the day.+Daily is right because a batch gives the agent a chance to notice that three+things you saved are about the same idea. Hourly does not.++**Link, weekly.** Connections need material to connect. Run it after a week of+ingestion.++**Lint, weekly.** After the linker, so it catches what that pass broke.++**Review, weekly.** The one output you actually read. Put it on the morning you+plan.++**Metrics, monthly.** Four numbers appended to a note. See+[metrics](../05-graphs/metrics.md).++## Setting one up++In Claude Desktop, the Schedule tab, then a new task:++```+Frequency: Daily, 7:00am+Folder: your vault+Prompt: File anything new in raw/ into the wiki following CLAUDE.md.+ Link it to existing pages. Update index.md and log.md. Commit+ with a message naming the run. Then write me three lines on+ what changed.+```++Or ask for it in a session: "set up a daily task at 7am that ingests raw/ and+summarises what changed".++From a terminal, `cron` or Task Scheduler calling Claude Code headless works the+same way, and is the better option if you want the run inside a git commit+automatically.++## What a run must produce++Three things, every time.++**A log entry.** Otherwise you cannot audit what happened while you were asleep.++**A commit.** One per run, with the run named in the message. This is what makes+a bad run revertible in one command instead of an evening.++**A report to you.** Even one line. A scheduled task that produces nothing+visible is one you stop trusting and then stop reading.++## Detecting silent failure++The failure mode is not a crash. It is a run that completes and does nothing+useful: the source was empty, the API call failed halfway, the instructions+matched no files.++Two cheap checks. Have the run report counts, not just completion, so "ingested+0 sources" is visible. And look at commit frequency once a month: a week with no+commits from the daily task means it has been failing quietly since Tuesday.++## Start manual++Run each job by hand for a week before scheduling it. You are checking that the+output is good enough to accept without reading it closely, because that is+exactly what scheduling means.++Schedule the ingest last. It is the one that writes most.++## Next++[Subagents and parallel work](subagents.md)diff --git a/docs/06-agents/skills-and-commands.md b/docs/06-agents/skills-and-commands.mdnew file mode 100644index 0000000..99886f1--- /dev/null+++ b/docs/06-agents/skills-and-commands.md@@ -0,0 +1,76 @@+# Skills and slash commands++Two mechanisms that look similar and do different jobs.++**A skill** teaches repeatable behaviour. It loads when relevant and shapes how+the agent does something, whether you invoked it explicitly or just described the+task.++**A command** is a shortcut for a task you run often. It points at a skill and+saves you typing the instructions.++The behaviour belongs in the skill. That way ingestion works the same whether it+was triggered by `/ingest`, by a scheduled task, or by you saying "add this to my+vault".++## What this repo ships++Four skills in [`skills/`](../../skills/README.md): ingest, lint, query, review.+Five commands in [`commands/`](../../commands/README.md), each a few lines+pointing at a skill.++Install them inside the vault at `.claude/skills/` and `.claude/commands/` so+they are versioned alongside your notes and travel with the vault.++## Writing your own++A skill worth writing has three properties: you do it repeatedly, you have+opinions about how, and the opinions are not obvious enough for the model to+guess.++Structure that works:++```markdown+---+name: skill-name+description: >-+ What it does. When to use it, written pushy, because agents under-trigger+ skills. Do NOT use for the tempting near-misses.+---++# Name++[Why this skill exists: what failure it prevents. This paragraph is the rubric+for every case the rules below do not cover.]++## Core rule+## Workflow+## Output format+## Calibration+## Example+```++The opening paragraph does more work than the rules. Rules cover the cases you+thought of; the reason covers the rest.++## Explain the why++"Never overwrite a contradiction" gets applied literally and fails on the edge+cases. "Never overwrite a contradiction, because the history of what you believed+is the thing this vault has that a search engine does not" generalises to+situations you never described.++All-caps NEVER without a reason is usually a missing explanation.++## Versioning++Skills live in the vault, so git tracks them. When output quality changes, the+skill diff is the first place to look.++Test a skill on three or four real cases before letting a scheduled task use it.+A flaw in a skill that runs nightly is a flaw in three hundred pages by the end+of the year.++## Next++[Guardrails](safety-and-guardrails.md)diff --git a/docs/06-agents/subagents.md b/docs/06-agents/subagents.mdnew file mode 100644index 0000000..28e5ae7--- /dev/null+++ b/docs/06-agents/subagents.md@@ -0,0 +1,55 @@+# Subagents and parallel work++Subagents run with their own context. That is the whole point: a subagent+reading thirty pages to answer a question does not fill the main session's+context with those thirty pages, only with the answer.++## When to fan out++**Research across many pages.** Send a subagent to read a cluster and come back+with a summary. The main session keeps its budget for the actual work.++**Independent sources.** Ingesting ten unrelated articles parallelises cleanly,+because none of them touch the same wiki pages.++**Verification.** One agent writes, another checks the pages against the sources.+Separate context is what makes the check meaningful; the same agent rereading its+own work mostly agrees with itself.++## When not to++**Related sources.** Three articles about the same topic must be ingested+sequentially. In parallel, each one creates the concept page independently and+you get three versions of it, or two of them are overwritten.++**Anything touching the index.** `index.md` and `log.md` are single files that+every run wants to append to. Parallel writes to them conflict or silently lose+entries.++**Small jobs.** Spawning a subagent costs a full context setup. For two files it+is slower than doing it directly.++## Merging parallel work++The rule that avoids most conflicts: subagents write to disjoint paths, the+parent merges.++Have each subagent report what it would write rather than writing shared files+directly. The parent applies the index and log updates in one pass, after all+subagents return. Page files themselves are safe to write in parallel as long as+two subagents were never given overlapping material.++Commit before any parallel run. When it goes wrong, it goes wrong across many+files at once.++## Cost++Parallelism does not reduce total token use, it reduces wall-clock time and+protects the main context. Four subagents cost roughly four times one.++That trade is worth it for a large backfill and pointless for a daily ingest of+five clipped articles.++## Next++[Hooks](hooks.md)diff --git a/docs/README.md b/docs/README.mdindex 81895a6..511b3da 100644--- a/docs/README.md+++ b/docs/README.md@@ -11,7 +11,7 @@ Setup is written in full. The rest is being written section by section; see the| [Ingestion](03-ingestion/README.md) | articles, video, PDFs, chat exports, voice, backfilling | **written** || [Structuring](04-structuring/README.md) | page types, linking rules, schema, contradictions | **written** || [Graphs](05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics | **written** |-| [Agents](06-agents/README.md) | roles, schedules, hooks, guardrails | in progress |+| [Agents](06-agents/README.md) | roles, schedules, hooks, guardrails | **written** || [Retrieval](07-retrieval/README.md) | query patterns, search, context budget | in progress || [Outputs](08-outputs/README.md) | writing, reports, publishing, learning | in progress || [Maintenance](09-maintenance/README.md) | linting, review cadence, git, privacy, scaling | in progress |diff --git a/docs/ROADMAP.md b/docs/ROADMAP.mdindex 83a5c03..2bf64ec 100644--- a/docs/ROADMAP.md+++ b/docs/ROADMAP.md@@ -211,36 +211,36 @@ The part most second-brain guides skip: what the graph is for and how to make it- Clusters as evidence of your real interests- Tracking metrics over time-## Agents (outline)+## Agents (done)Turning a one-off setup into a system that maintains itself.-- [ ] **Agent roles**+- [x] **Agent roles**- Ingestor, linker, reviewer, researcher- One job per agent and why- Handoffs between agents- Roles that are not worth automating-- [ ] **Scheduling**+- [x] **Scheduling**- Cadence per job: hourly, daily, weekly- Scheduled tasks, cron and CI options- What a run should produce- Detecting silent failures-- [ ] **Subagents and parallel work**+- [x] **Subagents and parallel work**- When to fan out- Context isolation between subagents- Merging parallel edits without conflicts- Cost of parallelism-- [ ] **Hooks**+- [x] **Hooks**- Triggering on file changes in raw/- Pre-write validation- Post-run linting- Keeping hooks fast-- [ ] **Skills and slash commands**+- [x] **Skills and slash commands**- Skills for repeated behavior, commands for repeated tasks- Where to store them so any agent can use them- Versioning your skills alongside the vault- Testing a skill before trusting it with the vault-- [ ] **Guardrails**+- [x] **Guardrails**- Never let an agent delete without a log entry- Write scopes: which folders are off limits- Dry-run mode