Make Your Second Brain Agent-Ready

Add an agent instruction layer to your PARA vault with skills and indexes.

Introduction

30 Second Summary

You spent time organizing your notes into a clean folder structure, but keeping that structure tidy is a full-time job on its own. Files pile up in the inbox, links go stale, and the system you carefully built starts to decay.

In this project, you will build an instruction layer on top of your Second Brain vault that teaches any CLI coding agent how to safely navigate, triage, and maintain your notes without you re-explaining the rules every session.

What You'll Build

Point any CLI coding agent at your vault and watch it read your AGENTS.md, discover your skills, and correctly sort an inbox note into the right folder using rules it learned from Markdown files you wrote.

By the end of this project, you'll have:

A root AGENTS.md that any CLI coding agent reads at session start to learn your vault's PARA structure, frontmatter schema, and safety boundaries, so it never corrupts your templates or strips your wikilinks.
A two-tier CONTEXT.md indexing system that lets agents find the exact note they need by reading a folder summary first, so they never waste tokens scanning every file.
Five composable Agent Skills following the agentskills.io open standard, giving agents step-by-step procedures for inbox triage, note creation, weekly reviews, note linking, and index rebuilding.
Secret Mission: Build an archive-stale skill that automatically detects completed and stale notes, moves them to your archive, and updates indexes across multiple folders.

Are there any prerequisites?

This project builds on the vault from Build Your Second Brain's Foundation, or you can clone the starter repo to jump straight in.

You will need familiarity with at least one CLI coding agent like Codex or Claude Code.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters. Your PARA-organized vault has the folder structure and templates, but right now no coding agent can understand or safely maintain it on its own.

Write the Root AGENTS.md

You have locked in what you're building: an agent-maintainable instruction layer on top of your Second Brain vault. The first piece of that layer is AGENTS.md, the root instruction file that every CLI coding agent reads at session start.

Without it, a coding agent dropped into your vault has no idea what the PARA folders mean, what frontmatter schema to follow, or what files it must never modify. The agent will guess, and it will guess wrong. Writing this file gives every agent a consistent starting context before it touches a single note.

In this step, get ready to:

Map each PARA folder to its purpose in a vault overview.
Document the frontmatter schema every note must follow.
Set safety boundaries so agents know what to never touch.

Create the vault overview

The vault overview is the first thing an agent reads. It needs to know what each folder holds, which note types belong there, and how notes move between folders.

Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
Type Cursor or VS Code and press Enter to open your text editor.
Open your Second Brain vault folder (second-brain) using File > Open Folder.
Create a new file in the root of your second-brain folder and name it AGENTS.md.
Paste the following content into AGENTS.md:

# Second Brain — Agent Instructions

## Vault Overview

This is a PARA-organized Obsidian vault. Every note is a Markdown file with YAML frontmatter.

| Folder | Purpose | Note types |
|---|---|---|
| 00 Inbox | Unsorted capture. The front door for anything new. | inbox |
| 01 Projects | Short-term efforts with a defined outcome and deadline. | project |
| 02 Areas | Ongoing responsibilities with a standard to maintain. | area |
| 03 Resources | Topics of ongoing interest, kept for future reference. | resource, moc |
| 04 Archive | Inactive items from the other three categories. | any (archived) |
| Templates | Templater templates for creating new notes. | N/A |

Notes move between folders as their status changes. A completed project moves to 04 Archive. A resource that becomes actionable moves to 01 Projects.

What does this section do?

The Vault Overview is the agent's orientation map. The table tells the agent exactly which note types belong in which folder, so it never puts a project note in 03 Resources by mistake.

The final two lines explain how notes flow between folders. This teaches the agent that folders are not permanent homes. A note's folder changes when its status changes.

Save AGENTS.md.
Switch to your terminal and confirm the file exists by running:

cat AGENTS.md

You should see the vault overview table with all six PARA folders listed, followed by the note-movement rules.

Seeing "No such file or directory"?

Make sure your terminal is in the second-brain folder. Run pwd to check.
Confirm you saved the file as AGENTS.md (all caps) in the root of the vault, not inside a subfolder.

Need more help? Why can't my terminal find AGENTS.md?

Document the frontmatter schema

Every note in your vault uses YAML frontmatter to store metadata like type, status, and tags. The agent needs to know exactly which fields exist and what values are valid, so it can read and write frontmatter correctly.

In AGENTS.md, place your cursor at the end of the file (after the line about projects moving to 01 Projects).
Add the frontmatter schema section by pasting this below the vault overview:

## Frontmatter Schema

Every note carries these universal fields in YAML frontmatter:

| Field | Required | Values |
|---|---|---|
| type | Yes | inbox, project, area, resource, moc, daily |
| status | Yes | inbox, active, done, stale, archived |
| created | Yes | YYYY-MM-DD |
| modified | Yes | YYYY-MM-DD |
| summary | Yes | One-line description of the note |
| tags | Yes | List of lowercase tags |

Resource notes add two extra fields:

| Field | Required | Values |
|---|---|---|
| source | Resource only | URL, book title, or reference |
| source_type | Resource only | article, book, podcast, video, course, conversation, email |

Why list every valid value?

Agents treat your frontmatter like a typed schema. If you tell the agent that status accepts five values, it will never invent a sixth like in-progress or pending.

The second table scopes source and source_type to resource notes only. This prevents the agent from adding a source field to a project note where it does not belong.

Save AGENTS.md.
In your terminal, verify the schema section was added by running:

grep "Frontmatter Schema" AGENTS.md

You should see ## Frontmatter Schema in the output, confirming the section is in the file.

Not seeing the heading?

Make sure you pasted below the vault overview, not inside it. The new section should start with ## Frontmatter Schema on its own line.
Check that you saved the file after pasting.

Still stuck? Help me add the frontmatter schema section to AGENTS.md.

Set naming conventions and safety boundaries

The agent also needs guardrails. Without clear boundaries, an agent might rename your templates, delete your Obsidian config, or strip wikilinks from a note during an edit.

In AGENTS.md, place your cursor at the end of the file (after the source_type row).
Add the naming conventions and safety boundaries by pasting this below the frontmatter schema:

## File Naming Conventions

- Note filenames use title case with spaces: `Meeting Notes From Standup.md`
- No special characters in filenames except hyphens and spaces
- Templates are named by type: `Inbox Note.md`, `Project Note.md`, etc.

## Safety Boundaries

Do NOT write to, modify, or delete files in these paths:
- `Templates/` — read-only reference for note structure
- `.obsidian/` — Obsidian plugin configuration

When editing any note:
- ALWAYS preserve existing wikilinks (`[[Note Name]]`)
- ALWAYS preserve existing YAML frontmatter fields (add fields, never remove)
- ALWAYS update the `modified` field to today's date when changing a note
- NEVER change the `created` field

What do the safety boundaries protect?

The two read-only paths (Templates/ and .obsidian/) keep the agent from breaking your vault's infrastructure. Templates are reference files the agent reads from but never writes to. The .obsidian/ folder holds plugin settings that could corrupt your vault if changed.

The editing rules are just as important. Preserving wikilinks ([[Note Name]]) ensures the agent never silently breaks connections between your notes. Protecting the created field keeps your note history accurate.

Save AGENTS.md.

Before you run the next command, how many level-two headings (##) do you expect to see in your AGENTS.md?

Verify all four sections are present by running:

grep "^## " AGENTS.md

You should see exactly four lines: ## Vault Overview, ## Frontmatter Schema, ## File Naming Conventions, and ## Safety Boundaries.

Seeing fewer than four headings?

Open AGENTS.md in your editor and scroll through it. Each section should start with ## followed by the section name.
If two sections appear merged, check that you pasted each block on its own line with a blank line before the ## heading.
Make sure you saved after the last paste.

Need help? Why is my AGENTS.md missing sections?

✔️ Awesome, I've got everything!

Great. Double check that you have saved AGENTS.md and you are ready to move on.

ⓧ I'd like to double check the full code

Your AGENTS.md should contain these three chunks in order. Scroll up and confirm each one is present:

Chunk 1: The # Second Brain — Agent Instructions heading, the ## Vault Overview section with the six-row folder table, and the two lines about notes moving between folders.
Chunk 2: The ## Frontmatter Schema section with the six-row universal fields table and the two-row resource fields table.
Chunk 3: The ## File Naming Conventions section with three bullet points, and the ## Safety Boundaries section with three read-only paths and four editing rules.

If anything is missing, scroll up to the relevant chunk and paste it into the correct position in your file.

Your vault now has a root instruction file that any CLI coding agent can load at session start. Next up, you will build the two-tier CONTEXT.md index so agents can find specific notes without reading every file.

Build the Two-Tier CONTEXT.md Index

Your AGENTS.md gives coding agents the rules. It explains the folder structure, frontmatter schema, and safety boundaries. What it cannot tell them is which notes actually exist in your vault.

Without an index, an agent must read every file in every folder to locate a single note. That wastes tokens and time. In this step, you will build a two-tier CONTEXT.md indexing system that gives agents a cheap lookup path: read the root index for folder-level summaries first, then drill into a specific folder only when needed.

In this step, get ready to:

Create a root CONTEXT.md that indexes all five PARA folders with summaries and note counts.
Create a per-folder CONTEXT.md inside each PARA folder with a note-level table.
Add index maintenance rules to AGENTS.md so agents keep the index in sync.

Create the root CONTEXT.md

The root CONTEXT.md is the first thing an agent reads when it needs to find a note. It lists each PARA folder with a one-line summary and a note count, acting as a top-level directory.

Create the root CONTEXT.md file by running this command:

cat > CONTEXT.md << 'EOF'
# Second Brain — Vault Index

Last updated: 2026-08-23

| Folder | Notes | Purpose |
|---|---|---|
| [00 Inbox](./00%20Inbox/CONTEXT.md) | 0 | Unsorted captures waiting to be triaged |
| [01 Projects](./01%20Projects/CONTEXT.md) | 0 | Active efforts with a defined outcome |
| [02 Areas](./02%20Areas/CONTEXT.md) | 0 | Ongoing responsibilities |
| [03 Resources](./03%20Resources/CONTEXT.md) | 0 | Reference material and MOCs |
| [04 Archive](./04%20Archive/CONTEXT.md) | 0 | Inactive items |
EOF

What does this file do?

This file mirrors the progressive disclosure model from the Agent Skills standard. An agent reads this single file to learn what folders exist, how many notes each holds, and what each folder is for.

Each folder row links to that folder's own CONTEXT.md (the second tier). The agent only follows those links when it needs note-level detail, keeping token consumption proportional to the query instead of the vault size.

Confirm the file was created by running:

cat CONTEXT.md

You should see a Markdown table with five folder rows, each showing a note count of 0 and a one-line purpose summary.

Seeing an empty file or an error?

Make sure you ran the command from the vault root directory (the folder containing AGENTS.md). Run ls and confirm you see your PARA folders listed.
If the heredoc syntax caused an error, check that the closing EOF sits on its own line with no leading spaces.
My CONTEXT.md is empty or malformed.

Create per-folder CONTEXT.md files

The second tier lives inside each PARA folder. Each per-folder CONTEXT.md lists every note in that folder as a table row with columns for filename, type, status, and summary. Right now the tables are empty because your folders have no notes yet.

Create all five per-folder index files in one go by running this loop:

for folder in "00 Inbox" "01 Projects" "02 Areas" "03 Resources" "04 Archive"; do
  cat > "$folder/CONTEXT.md" << EOF
# $folder — Note Index

| Filename | Type | Status | Summary |
|---|---|---|---|
EOF
done

What does this loop do?

The for loop iterates over your five PARA folder names.
For each folder, it creates a CONTEXT.md file containing a heading with the folder name and an empty Markdown table ready for note entries.
The $folder variable gets substituted into the heading, so each file gets a unique title like # 00 Inbox — Note Index.

Confirm the files were created by running:

cat "01 Projects/CONTEXT.md"

You should see a heading that reads # 01 Projects — Note Index followed by an empty four-column table with headers for Filename, Type, Status, and Summary.

Seeing a "No such file or directory" error?

Check that you are in the vault root by running ls. You should see your PARA folders (00 Inbox, 01 Projects, etc.) in the output.
If the folders exist but the loop produced no files, re-run the loop command. Make sure the closing EOF and done each sit on their own line.
My per-folder CONTEXT.md files were not created.

Add index maintenance rules to AGENTS.md

The index only stays useful if agents keep it up to date. Without explicit instructions, an agent might create or move a note and forget to update the CONTEXT.md files, making the index stale within one session.

Open AGENTS.md in your editor.
Scroll to the bottom of the file, below the ## Safety Boundaries section.
Add the following two new sections at the bottom of the file:

## CONTEXT.md Index System

This vault uses a two-tier CONTEXT.md index:

1. Root `CONTEXT.md` — lists all folders with note counts and one-line summaries
2. Per-folder `CONTEXT.md` — lists every note in that folder with type, status, and summary

When you create, move, or delete a note:
1. Update the source folder's CONTEXT.md (remove the row if moving/deleting)
2. Update the destination folder's CONTEXT.md (add a row if moving/creating)
3. Update the root CONTEXT.md note counts

## Skills

Composable skills are available in `.agents/skills/`. Read a skill's SKILL.md for step-by-step instructions on common vault operations.

What do these sections do?

The CONTEXT.md Index System section explains the two-tier structure to the agent and gives it a three-step procedure for keeping the index in sync whenever it touches a note.

The Skills section points the agent to the .agents/skills/ directory where composable skill files will live. You will create those skills in the next steps.

Save AGENTS.md.
Confirm the new sections are in place by running:

tail -20 AGENTS.md

You should see the ## CONTEXT.md Index System heading, the three-step maintenance procedure, the ## Skills heading, and the line pointing to .agents/skills/.

Not seeing the new sections?

Make sure you saved the file after editing. In VS Code or Cursor, press Cmd+S (macOS) or Ctrl+S (Windows).
Check that the new sections appear below ## Safety Boundaries, not inside it. Each ## heading starts a new top-level section.
My AGENTS.md is missing the new sections after saving.

✔️ Awesome, I've got everything!

Great. Double check you have saved AGENTS.md.

ⓧ I'd like to double check the full code

Your AGENTS.md is now complete for the rest of the project. Scroll through the file in your editor and confirm you have these six sections in order:

## Vault Overview with the PARA folder table (from Step 1).
## Frontmatter Schema with the six universal fields and two resource-specific fields (from Step 1).
## File Naming Conventions with title case and special character rules (from Step 1).
## Safety Boundaries listing read-only paths and editing rules (from Step 1).
## CONTEXT.md Index System with the two-tier description and three-step maintenance procedure (added in this step).
## Skills pointing to .agents/skills/ (added in this step).

Time for a final check. Before you run the next commands, predict what you expect to see in each output.

Verify the root index by running:

cat CONTEXT.md

You should see a three-column table with all five PARA folders, each showing a note count of 0 and a one-line purpose summary.

Verify a per-folder index by running:

cat "01 Projects/CONTEXT.md"

You should see a heading that reads # 01 Projects — Note Index followed by an empty table with four column headers: Filename, Type, Status, Summary.

Why are the tables empty?

Your vault has no notes yet (only templates and READMEs). As you or an agent adds notes, each note gets a row in its folder's CONTEXT.md. The maintenance rules you just added to AGENTS.md ensure agents always fill in these tables when they create or move notes.

Your vault now has both the rules (AGENTS.md) and the map (CONTEXT.md files). Next up, you will give agents step-by-step procedures they can follow by building your first composable Agent Skills.

Create Your First Agent Skills and Validate Them

Create Your First Agent Skills

Your vault's AGENTS.md teaches agents the rules, and your two-tier CONTEXT.md index lets them find notes cheaply. But agents still have no predefined workflows to follow.

The Agent Skills standard solves this by packaging multi-step procedures into composable SKILL.md files that any compatible agent can discover and execute. In this step, you will write your first three skills.

In this step, get ready to:

Create the .agents/skills/ directory structure.
Write three Agent Skills: inbox-triage, create-note, and weekly-review.

Create the skills directory and build the inbox-triage skill

The first skill you will build handles the most common vault operation: triaging notes from the inbox into the right PARA folder. Each skill lives in its own directory under .agents/skills/.

Create the directory structure by running this command:

mkdir -p .agents/skills/inbox-triage

Confirm the directory was created by running:

ls .agents/skills/

You should see inbox-triage in the output.

In your editor, create a new file called SKILL.md inside .agents/skills/inbox-triage/ and copy the following content into it:

---
name: inbox-triage
description: Triage a note from 00 Inbox into the correct PARA folder. Use when asked to process inbox, sort inbox, triage notes, or clear the inbox.
---

# Inbox Triage

## Steps

1. Read the root CONTEXT.md to confirm there are notes in 00 Inbox.
2. Read 00 Inbox/CONTEXT.md to get the list of notes to triage.
3. For each inbox note:
   a. Read the note's content and frontmatter.
   b. Determine the correct PARA category based on content:
      - Has a clear outcome and deadline → 01 Projects (type: project)
      - Is an ongoing responsibility → 02 Areas (type: area)
      - Is reference material, article, or learning → 03 Resources (type: resource)
      - Cannot be categorized → leave in 00 Inbox and skip
   c. Move the file to the destination folder.
   d. Update the note's frontmatter:
      - Change `type` to match the destination folder
      - Change `status` from `inbox` to `active`
      - Update `modified` to today's date
   e. Remove the note's row from 00 Inbox/CONTEXT.md.
   f. Add the note's row to the destination folder's CONTEXT.md.
4. Update the root CONTEXT.md note counts.
5. Report what was triaged and where each note landed.

What is a SKILL.md file?

The frontmatter block (between the --- markers) defines the skill's name and description. Agents read only these two fields at discovery time, keeping token costs low. This is called progressive disclosure.

The name must be lowercase, use only letters, numbers, and hyphens, and match the parent directory name exactly. The body after the frontmatter contains step-by-step instructions the agent follows when the skill is activated.

Still in the same file, add the following section below the last step:

## When Not to Use

- Do not triage notes that have `status: active` — they were already processed.
- Do not move Daily Notes (type: daily) out of the Inbox.

Why include guard rails?

The "When Not to Use" section prevents the agent from applying the skill in the wrong context. Without it, an agent might re-triage a note that was already processed or move a Daily Note out of the inbox.

Save SKILL.md.

✔️ Awesome, I've got everything!

Great. Double check you have saved SKILL.md before moving on.

ⓧ I'd like to double check the full code

Your .agents/skills/inbox-triage/SKILL.md should contain these sections in order:

The frontmatter and Steps section (from the first code block above).
The When Not to Use section (from the second code block above).

Scroll up and confirm both sections are present in your file, with a blank line between the last step and the ## When Not to Use heading.

Build the create-note skill

The create-note skill teaches agents how to create new notes using the right PARA template. It maps the user's intent to a template, fills in frontmatter, and updates the index.

Create the skill directory by running:

mkdir .agents/skills/create-note

In your editor, create a new file called SKILL.md inside .agents/skills/create-note/ and copy the following content into it:

---
name: create-note
description: Create a new note in the vault using the correct PARA template. Use when asked to create a note, add a note, start a new project, or capture something.
---

# Create Note

## Steps

1. Determine the note type from the user's request:
   - Quick capture → inbox (place in 00 Inbox)
   - Has outcome and deadline → project (place in 01 Projects)
   - Ongoing responsibility → area (place in 02 Areas)
   - Reference material → resource (place in 03 Resources)
   - Topic index → moc (place in 03 Resources)
2. Read the matching template from Templates/ to get the correct structure:
   - inbox → Templates/Inbox Note.md
   - project → Templates/Project Note.md
   - area → Templates/Area Note.md
   - resource → Templates/Resource Note.md
   - moc → Templates/MOC Note.md

What does this section cover?

Steps 1 and 2 handle the decision-making. The skill first classifies the user's request into a PARA type, then looks up the matching template in Templates/. This ensures every new note starts with the right structure.

Still in the same file, add the remaining steps and guard rails below the template mapping:

3. Create the new note file in the destination folder:
   - Use title case with spaces for the filename
   - Replace Templater syntax with actual values:
     - `<% tp.date.now("YYYY-MM-DD") %>` → today's date
     - `<% tp.file.cursor(1) %>` → leave blank for user
     - `<% tp.file.cursor(2) %>` → leave blank for user
     - `<% "---" %>` → `---`
   - Fill in frontmatter fields from the user's request
4. Add the new note to the destination folder's CONTEXT.md.
5. Update the root CONTEXT.md note count.
6. Report the created note's filename and location.

## When Not to Use

- Do not create notes directly in 04 Archive — that folder is for moved items only.
- Do not create notes in Templates/ — those are read-only.

Why replace Templater syntax?

Your vault's templates use Templater syntax like <% tp.date.now("YYYY-MM-DD") %> that only works inside Obsidian. Agents create files directly on disk, so the skill instructs them to replace these placeholders with actual values.

Save SKILL.md.

✔️ Awesome, I've got everything!

Great. Double check you have saved SKILL.md before moving on.

ⓧ I'd like to double check the full code

Your .agents/skills/create-note/SKILL.md should contain these sections in order:

The frontmatter, heading, and Steps 1-2 (from the first code block above).
Steps 3-6 and the When Not to Use section (from the second code block above).

Scroll up and confirm both sections are present in your file, in order.

Build the weekly-review skill

The weekly-review skill is the most complex. It composes multiple operations into a single workflow, including calling the inbox-triage skill you just wrote.

Create the skill directory by running:

mkdir .agents/skills/weekly-review

In your editor, create a new file called SKILL.md inside .agents/skills/weekly-review/ and copy the following content into it:

---
name: weekly-review
description: Run the weekly review checklist for the vault. Use when asked to do a weekly review, maintain the vault, or check vault health.
---

# Weekly Review

## Steps

1. **Empty the Inbox**: Read 00 Inbox/CONTEXT.md. For each note listed, run the inbox-triage procedure (read the inbox-triage skill for detailed steps). Report how many notes were triaged and where they went.

2. **Review active projects**: Read 01 Projects/CONTEXT.md. For each note with status "active":
   - Read the note and check if the Outcome section is filled in
   - Check if Next Actions has at least one item
   - Flag any project missing an outcome or next actions

What is skill composition?

Step 1 references the inbox-triage skill instead of repeating its instructions. This is composition: skills can call other skills by name, keeping each one focused on a single responsibility.

When an agent reads "run the inbox-triage procedure," it loads .agents/skills/inbox-triage/SKILL.md and follows those steps. You write the logic once and reuse it across workflows.

Still in the same file, add the remaining steps and guard rails below the project review:

3. **Check areas**: Read 02 Areas/CONTEXT.md. For each area note:
   - Check the modified date — flag areas not updated in over 30 days
   - Check if Active Projects section has links — flag areas with no linked projects

4. **Archive stale items**: Scan 01 Projects for notes with status "done". Move them to 04 Archive, update their status to "archived", and update both CONTEXT.md files.

5. **Report summary**: List all changes made during the review:
   - Notes triaged from Inbox (count and destinations)
   - Projects flagged for missing outcomes or next actions
   - Areas flagged as neglected
   - Notes archived
   - Updated CONTEXT.md files

## When Not to Use

- Do not run a weekly review on a vault with no notes — there is nothing to review.

What do the remaining steps cover?

Step 3 checks for neglected areas. Step 4 archives completed projects. Step 5 produces a summary report of every change the agent made during the review.

The final report is important. Without it, you would have to diff the vault manually to see what the agent changed.

Save SKILL.md.

Confirm all three skill directories are in place by running:

ls .agents/skills/

You should see three directories: create-note, inbox-triage, and weekly-review.

✔️ Awesome, I've got everything!

Great. Double check you have saved all three SKILL.md files before moving on.

ⓧ I'd like to double check the full code

Each SKILL.md file should contain these sections in order:

The frontmatter block and heading from the first code block for that skill.
The remaining steps and the When Not to Use section from the second code block for that skill.

Scroll up to each skill's substep and confirm both code blocks are present in your file, in order, with the content matching exactly.

Your vault now has three composable skills that any CLI coding agent can discover and execute. Next up, you will complete the skill set with link-notes and update-index, and bridge Claude Code with a one-line import.

Complete the Skill Set and Bridge Claude Code

Your first three skills give agents the ability to triage, create, and review notes. But your vault's real power comes from connections between notes.

Right now, the agent has no procedure for discovering related notes and linking them with wikilinks. It also has no way to rebuild the index if it drifts out of sync. In this step, you will create two more skills to fill those gaps, then bridge Claude Code so it reads the same instructions as every other agent.

In this step, get ready to:

Create the link-notes and update-index skills to complete your five-skill set.
Create a CLAUDE.md bridge file so Claude Code imports your AGENTS.md.

Create the link-notes skill

The link-notes skill teaches agents how to discover connections between notes by scanning CONTEXT.md summaries and tags. It also tells the agent when to create a new MOC (Map of Content) if a topic cluster emerges.

Create the skill directory by running this command:

mkdir -p .agents/skills/link-notes

Confirm the directory exists by running:

ls .agents/skills/

You should see four directories: create-note, inbox-triage, link-notes, and weekly-review.

Open .agents/skills/link-notes/SKILL.md in your editor and paste the frontmatter and first four steps:

---
name: link-notes
description: Find and create wikilinks between related notes in the vault. Use when asked to link notes, connect notes, find related notes, or build connections.
---

# Link Notes

## Steps

1. Read the root CONTEXT.md to get an overview of all folders and note counts.
2. Read each folder's CONTEXT.md to build a full list of notes with their summaries and tags.
3. Identify related notes by matching:
   - Shared tags across notes in different folders
   - Similar keywords in summaries
   - Explicit references (a project note mentioning a resource topic)
4. For each pair of related notes:
   a. Read both notes to confirm the relationship.
   b. Add a wikilink `[[Note Name]]` in the appropriate section:
      - In project notes: add to the `## Notes` section
      - In area notes: add to `## Active Projects` or `## Notes`
      - In resource notes: add to `## My Thoughts`
      - In MOC notes: add to `## Key Notes`
   c. Update the `modified` date on both notes.

What does this code do?

The frontmatter gives the agent a quick summary of when to use this skill. The name field must match the parent directory name (link-notes).

Steps 1-2 use your two-tier CONTEXT.md index so the agent reads summaries and tags instead of opening every note. Steps 3-4 tell the agent how to identify relationships and where to place wikilinks in each note type's structure.

Add the remaining steps and the "When Not to Use" section below step 4 in the same file:

5. If three or more notes share a topic and no MOC exists for it:
   - Create a new MOC note in 03 Resources using the MOC Note template
   - Link all related notes in the MOC's `## Key Notes` section
   - Add the MOC to 03 Resources/CONTEXT.md
   - Update the root CONTEXT.md note count
6. Report all links created and any new MOCs generated.

## When Not to Use

- Do not link notes that are in 04 Archive — archived notes should not gain new connections.
- Do not create duplicate wikilinks — check if a link already exists before adding.

What does this section do?

Step 5 handles automatic MOC creation. When three or more notes cluster around one topic, the agent creates a Map of Content to tie them together. This is the "emergent structure" your vault builds over time.

The "When Not to Use" section prevents the agent from linking archived notes (which should stay frozen) and from duplicating existing wikilinks.

Save .agents/skills/link-notes/SKILL.md.

Create the update-index skill

Over time, manual edits or agent mistakes can cause your CONTEXT.md files to drift out of sync with the actual notes. The update-index skill gives the agent a "rebuild from scratch" procedure that scans every note's frontmatter and regenerates all indexes.

Create the skill directory by running:

mkdir -p .agents/skills/update-index

Open .agents/skills/update-index/SKILL.md in your editor and paste the full skill:

---
name: update-index
description: Regenerate all CONTEXT.md files by scanning every note's frontmatter. Use when the index is out of sync, after manual edits, or when asked to rebuild the index.
---

# Update Index

## Steps

1. For each PARA folder (00 Inbox, 01 Projects, 02 Areas, 03 Resources, 04 Archive):
   a. List all Markdown files in the folder (excluding CONTEXT.md and README.md).
   b. For each file, read the YAML frontmatter and extract: type, status, summary.
   c. Build a Markdown table with columns: Filename, Type, Status, Summary.
   d. Write the table to that folder's CONTEXT.md, replacing the existing table content.
   e. Count the total number of notes in the folder.
2. Update the root CONTEXT.md:
   a. For each folder row, update the Notes count column with the actual count from step 1e.
   b. Update the "Last updated" date to today.
3. Report:
   - Total notes per folder
   - Any notes found with missing or malformed frontmatter (list filenames)
   - Total notes across the vault

## When Not to Use

- Do not run on a vault with no notes — the result would be empty tables, which is valid but pointless.

What does this skill do?

Step 1 walks through each PARA folder, reads every note's frontmatter, and rebuilds that folder's CONTEXT.md table from scratch. Step 2 updates the root CONTEXT.md note counts to match.

Step 3 asks the agent to flag any notes with missing or malformed frontmatter. This catches problems early instead of letting bad data silently persist in the index.

Save .agents/skills/update-index/SKILL.md.

Create CLAUDE.md

Claude Code reads CLAUDE.md at session start, not AGENTS.md. Without a bridge file, a Claude Code user gets zero vault context. A single-line import fixes this without duplicating any instructions.

Create CLAUDE.md at the vault root by running:

echo '@AGENTS.md' > CLAUDE.md

Verify the file contains exactly one line by running:

cat CLAUDE.md

You should see @AGENTS.md as the only output.

What does @AGENTS.md do?

The @ syntax in CLAUDE.md tells Claude Code to import the referenced file at session start. This keeps AGENTS.md as the single source of truth. Any updates you make to AGENTS.md automatically flow into Claude Code sessions too.

Before moving on, do a quick manual check that each skill follows the agentskills.io format:

Each SKILL.md starts with YAML frontmatter between --- markers.
The name field matches the parent directory name exactly (e.g. inbox-triage inside .agents/skills/inbox-triage/).
The description field is not empty.
Each file includes a ## Steps section and a ## When Not to Use section.

Confirm all five skill directories are in place by running:

ls .agents/skills/

You should see five directories: create-note, inbox-triage, link-notes, update-index, and weekly-review.

✔️ Awesome, I've got everything!

Double check you have saved all your files: .agents/skills/link-notes/SKILL.md, .agents/skills/update-index/SKILL.md, and CLAUDE.md.

ⓧ I'd like to double check the full code

Scroll up and confirm each file matches the code blocks above, in order:

.agents/skills/link-notes/SKILL.md contains the frontmatter (chunk 1) plus steps 5-6 and "When Not to Use" (chunk 2).
.agents/skills/update-index/SKILL.md contains the full skill definition in one block.
CLAUDE.md contains exactly one line: @AGENTS.md.

Your skill set is complete and your vault is cross-agent compatible. Any CLI coding agent that supports the Agent Skills standard can now discover and execute your five skills. Next, you can take on the Secret Mission to build a sixth skill that automates stale-note archival.

Secret mission

Build the Archive-Stale Skill

Your weekly-review skill already has an "archive stale items" step, but it only checks for status "done" in 01 Projects. Can you build a standalone archive-stale skill that handles compound criteria, scans three folders, and manages multi-folder CONTEXT.md updates?

Clean Up Your Resources

This project runs entirely on your local machine using free, open-source tools. There are no cloud resources or ongoing costs.

Resources you used:

Local second-brain vault folder containing the agent instruction layer you built.

Keep everything running

No action needed. Your AGENTS.md, CONTEXT.md files, and skills are plain Markdown files inside your vault folder. They persist as long as the folder exists.

Pause - I'll come back to this later

Close your editor. Everything is saved as files in your vault folder. Pick up where you left off by opening the folder again.

When you return, open a terminal in the vault root and you are ready to continue.

Delete - I don't want to use this again

Remove all agent-layer files without affecting your vault notes or PARA folders. Your original Second Brain structure stays intact.

Delete the agent instruction files and Claude Code bridge from the vault root by running this command:

macOS

rm AGENTS.md CLAUDE.md

Windows

del AGENTS.md, CLAUDE.md

Delete the root CONTEXT.md and all per-folder CONTEXT.md index files by running:

macOS

rm CONTEXT.md
rm "00 Inbox/CONTEXT.md" "01 Projects/CONTEXT.md" "02 Areas/CONTEXT.md" "03 Resources/CONTEXT.md" "04 Archive/CONTEXT.md"

Windows

del CONTEXT.md
del "00 Inbox\CONTEXT.md", "01 Projects\CONTEXT.md", "02 Areas\CONTEXT.md", "03 Resources\CONTEXT.md", "04 Archive\CONTEXT.md"

Delete the entire .agents/ directory containing all your skills by running:

macOS

rm -rf .agents/

Windows

rmdir /s /q .agents

Confirm the agent layer is removed by running ls. You should see your PARA folders and Templates/ still present, with no AGENTS.md, CLAUDE.md, CONTEXT.md, or .agents/ in the listing.

Nice Work!

Nice work! You have built a complete agent-maintainable instruction layer on top of your PARA-organized Second Brain vault. Any CLI coding agent you point at this repo can now discover, navigate, and safely modify your notes through standardized files you wrote from scratch.

You've learned how to:

Write a root AGENTS.md that teaches any CLI coding agent your vault's PARA structure, frontmatter schema, naming conventions, and safety boundaries.
Build a two-tier CONTEXT.md indexing system that lets agents find notes without reading every file, keeping token costs low.
Create five composable Agent Skills (inbox-triage, create-note, weekly-review, link-notes, update-index) following the agentskills.io open standard and bridge Claude Code with a one-line CLAUDE.md import so the same instructions work across Codex, Pi, Hermes, and Claude Code.
Secret Mission: Build an archive-stale skill that automates stale-note detection and archival with multi-folder CONTEXT.md updates.

Ready to quiz yourself?