SmartFolder Skill (v6.6.0)
Turn the target folder into a SmartFolder: a self-maintaining navigation-and-knowledge layer
over the real files, so the user, other people, and future Claude sessions can operate in it with
full context — finding things by location, and drawing on synthesized knowledge that no single file
contains — without opening every file.
How this skill runs
This is interactive, customized work, not a template application. The user will describe their
intentions and goals in their own words — treat that as the requirements and this skill as the
method. Expect an interview; the design is worked out together through the phases below, each
ending at a review gate.
Design stance. Only the invariants and safety rules below are fixed. Everything else is
decided per folder through a needs diagnostic, guided by principles, three real precedents, and
the bundled kit. Detailed specification of flexible decisions is deliberately avoided: being
overly prescriptive about flexible design choices becomes proscriptive in implementation — it
forbids better designs. Where this skill is silent, design from the principles and precedents
rather than asking for a rule.
Two kinds of bundled content, never to be confused. assets/kit/ is the kit: working
exemplars and scripts that get adapted and deposited into the user's folder (Phase 5).
Top-level references/ is the opposite — files this skill reads on demand when a branch fires
and never deposits: references/DEPOSIT_SPEC.md (the complete Phase-5 deposit specification),
references/UPGRADE_PATH.md (the full existing-SmartFolder upgrade path), and
references/VERSION_HISTORY.md (the full changelog). Nothing from references/ ever lands
in a built folder.
Non-negotiables (safety — these override everything else)
- Nothing moves, gets renamed, or gets generated until the user approves a plan. Staged work,
review gates.
- Back up first (zip/tar the tree) before any move or rename. Log every move/rename to a
move-log.csv. After moving, verify by content hash against the backup — not just counts.
- Never delete. Instead, move unneeded files to a single manual-delete folder at the root;
one such folder per SmartFolder. What the staging rule
protects is a category, not a location: staged content never re-enters the folder's
knowledge layer — never read, quoted, reconciled against, or restored from. One exception:
a single light manifest (
_README.md), written at staging time by the session that staged —
one line per item: what moved, when, why, where the surviving copy is — so the owner isn't
emptying unlabeled files on trust. The separating test: the manifest may be consulted only
to answer a question about the disposal itself ("is it safe to empty this? why is that in
there?"); any other use, including answering anything about the folder's subject matter, is a
violation of the rule, not an exercise of the exception. The manifest is not curated, earns no
maintenance, and dies with the contents — when the owner empties the folder, it resets.
- macOS bundles are atomic (
.rtfd, .oo3, .key, .pages, .numbers, .goodnotes,
.webarchive, companion *_data dirs, and kin): rename if needed, never recurse into or write
inside.
- Never clobber existing guides, indexes,
CLAUDE.md, or AGENTS.md without explicit OK. If SmartFolder
scaffolding already exists, this is an upgrade, not a build (see Existing SmartFolders).
- Don't modify file contents. Only add guide/derived files and (if approved) move/rename. If a
folder is shared or off-limits, work from a copy.
- Never guess. Flag anything you can't confidently summarize; a confidently wrong summary or
synthesis is worse than none.
One procedure in this skill reaches the network — the monthly version check this skill deposits
into every folder it builds (Phase 5); everything else is local files. The check degrades to
silence when the network doesn't answer, so no folder ever depends on connectivity.
The invariant core (every SmartFolder shares these)
The tier model — read top-down, stop when you have enough:
- Tier 1 (resident): one resident root manual —
CLAUDE.md; in the dual profile it exists as
two byte-identical files, CLAUDE.md and AGENTS.md (see Root files by agent population) —
the only content that auto-loads every session and
survives compaction. Protocol + conventions + behavioral rules + a thin top-level orientation.
Keep it lean (under ~150 lines); detail lives in the files it points to.
- Tier 2 (on demand): a
_README.md in each meaningful folder — a local router describing
its own folder and mapping its immediate children. Tiny/leaf folders fold into the parent's guide.
- Tier 3 (on demand): derived, digested knowledge — per-file sidecars (
<stem>_Summary.md),
folder syntheses (_Synthesis.md), and whatever status surfaces the folder's needs call for
(boards, decision logs, indexes, hubs). Which of these exist, and in what proportion, is the main
design decision (see The diagnostic).
- Raw files: the bottom of the waterfall — opened only when a digest won't do.
Navigation is by location, not a central index. The root file states the protocol — before
working in or answering about a folder, read its _README.md first — and each guide routes to its
own children. Nothing global to keep in sync. Only the root file is named CLAUDE.md; per-folder
guides stay _README.md (nested CLAUDE.md auto-loading is a Claude-Code-specific, after-the-fact
behavior — the explicit protocol is portable across products and predictable).
Root files by agent population (dial 7). Single-agent folders keep one root CLAUDE.md and pay
none of what follows. Where the dial says other assistants may work the folder, use guarded
duplication: byte-identical CLAUDE.md and AGENTS.md, each carrying a one-line reciprocal
instruction — any change to one is applied to the other before the task completes. AGENTS.md is
canonical on divergence; repair by re-copying from it, and add a root-files-differ check
(cmp AGENTS.md CLAUDE.md — silence means identical) to the folder's integrity script, or to its
runbook verification list if it runs none. Never assemble either root file with @ imports:
some surfaces inject CLAUDE.md verbatim with no import expansion, so an imported manual arrives
empty — no error, no trace. Why duplication: the project-root file is re-read from disk and
re-injected after compaction, which conversation content is not, so a real file — not a pointer to
one — is what survives a long session on every surface; and duplication's failure mode, divergence,
is mechanically detectable where a stub's mid-session staleness is not. In dual folders, deposited
wording is agent-neutral ("ask your AI assistant"), lock files record the holder "via
<assistant/surface>", and nothing relies on HTML comments being invisible — other agents read them
as content. The root file is context, not enforcement: deposited wording never promises compliance.
Every derived surface is dated and ranked:
- Every guide, synthesis, and status surface carries an
As of [YYMMDD] line.
- Recency wins: when two dated surfaces disagree, the more recent as-of date wins.
- Raw beats derived: a synthesis or summary is AI interpretation; the raw file wins on conflict.
- The filesystem beats the map: a live directory listing outranks any guide's file map.
Derived knowledge surfaces — where the added value lives. The derived layer holds knowledge
that no single file contains and that would otherwise require tedious browsing of many files.
Synthesis (_Synthesis.md) is the archetype: it exists only where the whole exceeds the parts,
correlating, combining, and commenting across a folder's files to yield the holistic story — arcs,
patterns, cost roll-ups, cross-system connections, recurring failure modes. Synthesis has siblings,
distinguished by the kind of tedium they remove: a status board (currency over time — one dated
line per workstream plus its next gate); a longitudinal tracker (one subject — a medical issue,
a negotiation arc, an easement — threaded across many files and years); a decision log
(append-only dated record of what was decided, with sources); cross-folder maps and hubs
(maintenance calendars, vendor directories, sensitive-info maps, entity indexes); and computed
views (dashboards, charts, extract tables built from the structured layer). The taxonomy is open —
invent the species this folder's questions call for.
All species share one discipline: an As of [YYMMDD] header; claims anchored in-narrative ("through
[date]…"); stated provenance (what it was derived from, as of what state — which doubles as the
staleness test) and a decay condition (when it might begin to be wrong); a label as derived AI
analysis (raw wins); and the one-line breadcrumb "To refresh: ask your AI assistant to update
this." The discipline belongs to every derived surface, Tier-2 guides included: a
_README.md's descriptive front matter carries its as-of line, provenance, and decay condition
like any Tier-3 species. The behavioral rule — offer to refresh any derived surface materially
behind its sources before relying on it — lives once, in the root file, not in each file.
Write forward, not backward (live surfaces). A live surface — one whose subject is still
moving: a board row, a README's front matter, the synthesis of an ongoing system — leads with the
present: current state + what's next, one screen, written from now looking forward. The test: a
newcomer's first screen answers "where do things stand?" without summing dated patches. Refreshing
means rewriting the front matter, not appending a dated delta — appending is the writer's cheap
path, but it shifts the cost onto every future reader. Small deltas may accrete between rewrites;
at a chapter boundary (a close, a kill, a pivot, a replacement) the surface is rewritten
state-first and the accumulated narrative is demoted whole into a labeled history section or a
sealed, dated index, with one pointer from the front matter — never deleted or summarized away
(that is what makes rewriting safe). Tripwire: front matter carrying more history than present
state is a boundary in disguise — a rewrite is due. Archival syntheses of completed arcs already
comply: their "present" is the finished story. Deposit this rule in each SmartFolder's root
CLAUDE.md (procedure in the runbook) — accretion is a maintenance-time failure, and the skill
won't be there.
Sidecars (<stem>_Summary.md) are caches, not commentary. A sidecar pays rent when the raw
file's read-cost × consultation-frequency is high. Typical triggers: long or dense PDFs and
transcripts (re-reading a 60-page transcript can cost a session 100K+ tokens); scanned, OCR'd, or
handwritten material where extraction is slow or error-prone; formats Claude reads poorly or not at
all (the sidecar is then the only machine access); authority documents — contracts, reports, rulings
— whose exact terms will be asked about repeatedly (capture the key terms plus last-mile pointers:
"signature page is p. 14"); files whose payload is visual; and files a synthesis leans on, where the
sidecar doubles as the synthesis's provenance anchor. Skip routine items, media dumps, and anything
the folder's README or synthesis already covers. Sidecars move with their file.
Self-orientation from anywhere: each _README.md opens with one line noting it is part of a
SmartFolder whose protocol lives in the root CLAUDE.md — so a session that mounts a subfolder can
still find the system.
Proportionality: every artifact must pay rent — real signal against its maintenance cost. No
rote guides, no unwarranted syntheses, no machinery a folder's needs don't justify.
Self-containment: the finished SmartFolder carries its own maintenance payload (see Phase 5).
After the build, this skill is only needed to seed new SmartFolders — never to maintain this one.
Naming (the default house convention — adapt to the folder's own tradition where one exists):
- Dates lead, as
YYMMDD or YYMM, no dashes; YYYY only when just the year is known. Decode
2-digit years by century (≥90 → 1900s). If the archive spans the century boundary or the 1980s,
raise it in Phase 2 — string sorting breaks across centuries — and agree on handling.
- PascalCase within one concept, underscores between concepts; theme-first so like items
cluster:
DATE_Type_Specifier.ext (e.g. 2312_WaterReport_FairfaxCounty.pdf).
- Where a name is vague or wrong, peek inside and name by real content; add missing extensions;
fix problem characters (colons,
#, hidden/non-breaking spaces, trailing spaces). Bulk-rename
with globs, not hardcoded names, and verify each rename happened.
- Bulk media/photo dumps: batch-name, don't curate each; describe the group in the guide.
The diagnostic (design through interview, not menu)
Before proposing scaffolding, learn the folder's needs — from the user's stated intentions, from
Phase-1 exploration, and by asking (AskUserQuestion works well here). The dials:
- Writers and users. Who adds or edits files — Claude only, one human, several humans? Via a
sanctioned intake path or directly? How technical is each? And whose files are they? If
this reveals the minority case — the folder holds files of an owner who is not driving or
coordinating the build — suggest winning the owner's buy-in before the plan executes: a warm,
non-technical one-page note saying what will move and why, with nothing deleted (the kit's
Example_Owner_Letter.md models the shape and tone). Most folders are built by, with, or under
the authority of their owner and pass through with no mention — this is a conditional offer,
never a standing step. Usage changes over time, so the deposited growth menu carries the same
trigger forward. A second conditional offer hangs on the same dial: where several people will
use the folder across sessions, offer the session-flags register (the kit's
Example_SESSION_FLAGS.md) — a person-addressed notification surface for "next time X is
here, tell or ask them Y," whose content and state live entirely in the register while the
root file carries only the trigger. Collaborative folders only — a single-writer folder is
never shown it; the deposited growth menu carries the same conditional row forward, so a
folder that grows into multi-user life can reach it later. And where the folder is shared over
a cloud-sync service, state the offline-availability requirement here, while the multi-writer
arrangement is being designed: every collaborator's machine must hold the folder offline —
"Make Available Offline" (Dropbox), offline access (Google Drive), or the service's
equivalent — or that person's sessions read placeholders. A per-machine setting, never a
one-time folder setting.
- Change velocity. Archival (rarely changes), slow-drip, or live and fast-moving?
- Dominant question type. What will people mostly ask here — navigation ("where is X?"),
wisdom ("how does this work? what matters? what's due?"), or status ("where do things
stand?")?
- Enforcement posture. Should integrity machinery offer (advisory, non-blocking) or gate
(hard checks before work proceeds)?
- Authority model. Raw files only? Hand-authored primary notes that must stay primary and be
kept in sync? Volatile facts needing a single dated source-of-truth surface?
- Audience and tone. Who reads the guides — and how plain must the language be?
- Agent population. Will AI assistants other than Claude work this folder? The relevant
population is assistants that work in folders, not chat alone. Ask in plain product terms,
without assuming the user knows what any of these are: "Will this folder be used only with
Claude (Cowork or Claude Code), or also with other AI tools that work in your folders —
OpenAI's ChatGPT Work or Codex, Google's Gemini (Spark or CLI), Microsoft Copilot, Cursor, or
something else — now
or someday?" Only Claude → single profile: one root
CLAUDE.md, none of
the dual tax. Anything else → the dual profile (see Root files by agent population). If the
user is unsure, choose single: converting later is one copy plus the reciprocal lines.
Allocation principles (the actual design law):
- Spend the derived-layer budget where the dominant question lives. Navigation-heavy → rich
_README.md coverage. Wisdom-heavy → syntheses (and perhaps a one-page hub). Status-heavy →
boards, decision logs, indexes, sidecars.
- Control machinery scales with write-traffic × writer count: none → a casual tripwire →
intake discipline with locks and hard integrity gates. Never more than the traffic justifies.
- File-map richness: enumerate files only where names can't speak for themselves, and scale
enumeration down as change velocity rises — a good renaming pass and a file map are substitutes;
in a fast-moving folder, annotate and route rather than list.
- Tone to the least technical reader who will use the folder.
- Invent freely; skip freely. Derive machinery this list doesn't name if the needs call for it;
omit anything here that doesn't pay rent. Confirm significant inventions with the user before
building.
Precedents (case law, not templates)
Three real SmartFolders built with this method. Note what they share (the invariant core, exactly)
and how each spends its budget differently — driven by its needs, not by a feature list.
- The Archive — a 22-year, ~6,700-file family records archive; one technical user; near-zero
change velocity; dominant question "where is X?". Allocation: a
_README.md in every meaningful
folder with full annotated file maps (stable, because content rarely changes); only two syntheses,
placed at genuine arc points (the whole academic record; a school-search saga); no sidecars, no
locks, no boards. A generator script emits guide scaffolding and stamps content-hash markers so
re-runs preserve hand edits; a documented periodic sweep handles intake.
- The Advisory folder — estate/property records shared with a non-technical owner; owner edits
files directly; dominant questions operational ("what's due? how does this system work?").
Allocation: ~40 per-system syntheses seeded from the owner's hand-authored MASTER notes (which
stay primary, with a stated sync protocol), plus a one-page Operations Hub (maintenance calendar,
vendor directory, sensitive-info map). Integrity is a non-blocking daily tripwire — a watcher
that detects direct changes and offers dispositions, never gates. Warm, jargon-decoded tone;
gotchas storytold; polished owner-facing PDFs at the root.
- The Operational folder — a live, multi-user deal workspace shared on Dropbox; several writers;
daily change; dominant question "where do things stand?". Allocation: a one-screen status board,
per-initiative decision logs and document indexes, and per-file summary sidecars on most documents
so raw files rarely need reopening. Control machinery is hard: all new content enters through
an inbox workflow under a courtesy lock; a content-hash manifest with a session-start scan and a
review queue makes colleague edits surface within a day; prescriptive tone; explicit lifecycle
(closed initiatives archived with closing memos).
License clause: these are precedents, not menus. Cite them, interpolate between them, depart
from them — the test is whether the resulting scaffolding serves this folder's diagnostic, not
whether it resembles an example.
The companion kit (bundled — assets/kit/)
Working artifacts drawn from the three precedents ship with this skill: the integrity and
change-tracking scripts, a guide generator, an inbox workflow and lock file, a drift-disposition
matrix, and growth menu / owner letter / owner guide / status board /
decision log / review queue / operations hub / synthesis / guide / sidecar exemplars. Integrity
machinery comes in three species — the advisory tripwire (offers), the hard gate (blocks), and
the generator's content-hash markers (protect generated guides from regeneration) — and the matrix
is the hard gate's companion reference, not a rung the advisory tier is climbing toward. Start from
assets/kit/00_KIT_README.md, which maps each artifact to the diagnostic dials that warrant it.
That README's table is the index — it answers whether an artifact is warranted; the exemplar is
the specification of what the artifact is — never of what yours must be. Open the exemplar
before authoring any surface it models — a step, not a recommendation; per artifact, at authoring
time. Then decide freely: adopt, adapt, or depart — the exemplar is a well-built guide from one
folder's life, and this folder's diagnostic, profile, and owner govern what is actually built.
Where your departure changes a form a reader would notice, say so and why, at the point of the
decision.
Kit artifacts are starting points to adapt, never to transplant wholesale: the markdown
exemplars are fictionalized (real shapes, invented content), the scripts' sample configuration and
example content are likewise invented, and the scripts need their paths, conventions, and
ignore-lists adapted to the target folder. Scripts destined for the target
SmartFolder are copied into its meta folder in Phase 5.
The build (phases — each ends at a review gate)
Phase 0 — Intent. Absorb the user's stated goals and constraints; confirm scope (this folder
only, or siblings too?). Touch nothing.
Phase 1 — Explore and report. Walk the tree: folder/file counts, depth, biggest areas,
file-type mix, the naming/date conventions actually in use (they may differ per subfolder — honor
detected conventions rather than imposing one rule everywhere). Detect existing instruction files
(CLAUDE.md, READMEs, AGENTS.md, .claude/) → route to the upgrade path. Flag oddities that
change the plan: problem characters, no-extension legacy files, scanned PDFs with no text layer,
locked files, mislabeled files. On a cloud-synced path (Dropbox, Google Drive, or similar), reads
that stall, fail, or return empty content usually mean online-only placeholders, not broken files
— name the fix rather than diagnosing file-by-file: the folder needs "Make Available Offline"
(Dropbox), offline access (Google Drive), or the service's equivalent, set per machine. Note
synthesis candidates — folders whose files together tell a
story — and folders that are mere piles of like items (no greater whole; skip).
The front-door gate — after the look, before any commitment. When this skill fired on a plain
organize-request — a folder to organize with no scheme the user has already chosen — do not
commit silently to either path. Phase 1's mere-piles skip applies first: twelve holiday photos
never hear the offer. Otherwise offer the method, once, in plain terms: "I have to understand
this folder to organize it well — want me to write down what I learn while I'm in here, so the
next person or session doesn't start over?" The fork is explicit and both paths are nameable —
build (continue into Phase 2) or just-organize (do the requested work well and stop). A
declined offer deposits nothing: no scaffolding, no marker, no record of the decline — whether to
raise it again is ordinary conversational judgment. A request that supplied its own scheme was
never this gate's business: execute it, no offer.
Phase 2 — Diagnose and decide. Run the diagnostic interview. Then propose, for the user's
approval: the profile (dial readings + the allocation they imply + rationale), the
reorganization scope (guides only / group into chapters / full restructure with renaming), the
naming convention, and a dry-run plan showing where every folder and loose file lands and which
folders get which derived surfaces. While naming is on the table, mention that at close-out the
skill will suggest appending SmartFolder to the folder's own outer name (Phase 6 makes the
offer) — so it is no surprise later.
Phase 3 — Sample. One chapter end-to-end. Judge it together on whether the guides and any
synthesis are genuinely useful — not just present.
Phase 4 — Apply. Execute moves/renames with logging and hash verification; author guides and
syntheses from real contents — never auto-fill filler prose. Size the approach to the job: a
generator script for scaffolding on large trees (prose in a separate content layer; content-hash
markers so re-runs preserve human edits; hand-written guides just carry their as-of line), direct
writing on small ones. At scale, fan out parallel sub-agents on disjoint scopes with their own move
logs and required integrity reports; keep judgment calls and shared-file writes single-threaded.
Phase 5 — Deposit the infrastructure. The SmartFolder must be self-contained: after this
phase, maintenance never needs this skill. Read references/DEPOSIT_SPEC.md — the complete
deposit specification, bundled in this package — in full before authoring any deposit, and reopen
it whenever Phase 5 resumes after a session boundary (this stub survives compaction; the
reference does not). The list below is the index, never the spec:
- the root
CLAUDE.md — and its byte-identical AGENTS.md twin in the dual profile;
- the four close-the-loop rules;
- the session-boundary prompt and the root manual's Session boundaries section;
- the maintenance procedures — consolidated in a runbook by default, distribution licensed
with the arrangement recorded in the recorded profile;
- the recorded profile, any adapted kit scripts and generator, move logs, and the
backup manifest;
- the growth menu;
- the retained kit — the whole of
assets/kit/, byte-for-byte, a stable-named readable
subtree in the meta home: the menu's implementation library;
- the version baseline — recorded always; the
.skill package deposited when already in
hand, never procured — carrying the monthly version check;
- the developer-feedback offer at build close-out, composed only on acceptance;
- the version-upgrade review, deposited among the maintenance procedures.
Phase 6 — Verify.
- Coverage invariant: every meaningful folder has a
_README.md or is explicitly covered by its
parent's; no filler guides or unwarranted syntheses crept in.
- Root
CLAUDE.md is lean, loads as project instructions, states protocol + precedence + refresh
rule; orientation links resolve.
- Every derived surface carries its as-of line, provenance, and a decay condition; flag any derived
surface whose sources are newer than its as-of date.
- No derived files inside bundles or trash; internal links resolve; content-hash check against the
backup shows no loss; spot-check summaries and syntheses against raw contents.
- Dual profile only:
cmp AGENTS.md CLAUDE.md is silent, and a parity probe passes for every
agent that will work the folder — plant unguessable content in the root files, ask each agent to
quote it back, check for exact match, and give explicit permission to answer "I see none."
Never ask an agent to confirm it "has the instructions": a session without them will confabulate
a plausible answer rather than report absence.
- The root file's close-the-loop list names exactly the surfaces that fail the locality test — no
more, no fewer — swept against the entire surface inventory, with every external-state
surface on it by definition; and every listed surface states its own decay condition.
- Prescriptive, dateless files (the root manual, the runbook, deposited READMEs) carry no
point-in-time state that a status surface owns; spot-check a sample of the source-pointered
constants that remain against their sources — a sample, not an audit; the pointer's real work
happens at edit time.
- Sweep the deposited surfaces for capability language — "is blocked", "cannot", "typically
can't", "available", and kin. The sweep is a finder, not a verdict: judge each hit — is the
capability the rule's genuine precondition (keep it, and it must state its false branch), or
the justification for a rule that applies regardless (strike the claim, keep the rule)? It
must not fire on legitimate conditionals — dual-profile rules, conditional registers, and
degraded modes are correct as written.
- The root's Session boundaries section exists, one line per active duty, each pointing at a
procedure file that resolves; the deposited
VERSION_BASELINE.md carries the check procedure,
both URLs, and the Last checked stamp — and where the folder runs integrity machinery, the
baseline is a sanctioned write target.
- The maintenance procedures exist and are findable where the recorded profile says (a
consolidated runbook, in most folders); the meta folder holds the recorded profile, growth
menu, version baseline, and retained kit; the maintenance loop works without this skill.
- The retained kit is byte-identical to this package's
assets/kit/, carries no generated
guides, sidecars, or syntheses inside it, sits on the drift machinery's ignore-list where any
runs, and every growth-menu pointer naming a kit artifact resolves into it — no package,
installed skill, or network required.
At close-out, once — the outer-name suggestion (an offer, deliberately not a verification
check — nothing about it is checkable, and a check that always passes trains people to ignore the
list): recommend the user append SmartFolder to the folder's own name — Acme Consulting →
Acme Consulting SmartFolder — so a built folder is recognizable from outside any session: in a
file browser, a backup job, a list of connected folders. A space separates by default; the
folder's own separation convention wins (Acme_Consulting → Acme_Consulting_SmartFolder). Skip
the offer when the name already ends in the suffix, case-insensitively. The name is the owner's,
and any rename happens only on their say-so. In most environments the session cannot rename its
own root: the root folder is the handle the environment hands the session, not a file inside the
tree, and renaming it mid-session severs the reference the session runs on. There, the offer states
both steps, for the owner to carry out between sessions: rename the folder, then re-point
whatever holds it under the old name — in Cowork, re-select the folder; in Claude Code, update
the project's path; in any other assistant, whatever it uses to locate this folder — or a future
session will not find it. Where the environment does let the session rename the root and re-point
its own reference safely, it may offer to do that itself — verify the connection afterward, and
the two-step instruction above remains the fallback. Offer once; accept a no without argument and
do not re-raise in this session; record nothing — the outer name is the owner's, and out of this
folder's scope once built.
Existing SmartFolders (the upgrade path)
When Phase 1 detects SmartFolder scaffolding already present — a root CLAUDE.md/AGENTS.md,
_README.md routers, a meta folder with a runbook or version baseline — this is an upgrade,
not a build. Read references/UPGRADE_PATH.md — the full upgrade path, bundled in this
package — before proposing anything. It carries the version-against-version review route, the
accretion audit, and the standing repairs a session offers because deposited machinery never
self-heals (the version check, capability-resting rules, pre-identity flags registers, the
growth-menu sentence, the outer-name suffix). The non-negotiables bind on this path too, and the
folder's recorded profile — not this skill's defaults — governs unless the user says otherwise.
Working style
Use a task list; keep updates concise; show samples before mass-applying; ask before underspecified
work. When new content arrives later, any session should be able to run maintenance from the
deposited procedures (the runbook, in most folders) — add guides for new folders, refresh stale
guides and syntheses while preserving
manual edits, and re-run the verification steps — without this skill installed.
1---2name: create-smartfolder3description: Turn a folder hierarchy into a SmartFolder — a tiered navigation-and-knowledge layer over the real files, so people and future Claude sessions can operate in it with full context and synthesized knowledge without opening every file. Use whenever the user asks to create, build, or convert a folder into a SmartFolder, "smartfolder-ize" a directory, add a CLAUDE.md / README / synthesis layer over files, reorganize an archive or document repository so Claude can navigate it, or review, upgrade, or extend existing SmartFolder scaffolding — even if they never say "SmartFolder" but describe wanting a folder of records made self-describing, navigable, or Claude-ready. Also use when asked to organize or reorganize a folder without a scheme the user has already chosen, so deciding it requires understanding the contents: look first, then offer this method rather than assuming it. Not for file operations already specified — renaming to a stated pattern, moving named files, de-duplicating.4---56<!--7 ============================================================8 SmartFolder Skill — a skill for building SmartFolders.9 Version: v6.6.0 — last changed [260826].10 v6.6.0: the version baseline streamlines — record always,11 archive when in hand, never procure — and the deposited12 Offer A gains its missing false branch (RM-27); cloud-sync13 collaboration guidance — offline availability, per14 collaborator machine (RM-25); an opt-in anonymized15 developer-feedback email, offered at build close-out and16 on a milestone schedule, composed only on acceptance17 (RM-26); the maintenance-procedures deposit restated —18 runbook as default, not mandate (RM-28); Phase 5's deposit19 spec moves to references/DEPOSIT_SPEC.md (PD-26); a20 kit-consistency check joins the release procedure,21 workspace-side, nothing in this package (RM-29); and every22 finished folder retains the whole kit byte-for-byte as a23 readable Kit/ subtree in its meta home, so the growth menu24 and feedback procedure resolve locally with no package,25 skill, or network (RM-30).26 Full version history: references/VERSION_HISTORY.md (in this27 package; read on demand, never deposited) and CHANGELOG.md28 at github.com/idea2go2go/smartfolder-skill.29 Line budget: 550 lines is a soft hygiene tripwire, not a30 cap — this file divides by task coherence (bounded task31 manuals live in references/), never to shed lines for32 their own sake; crossing 550 triggers a deliberate33 refer-out rethink. Line and word counts are reported at34 each release's verification.35 Created by Paul Hess (paul@hess.club).36 If you have questions, suggestions, or problems using this37 skill, please contact Paul at paul@hess.club.38 The bundled kit (assets/kit/) draws its shapes and discipline39 from Paul's live SmartFolders; the exemplars, and the sample40 configuration and example content in the scripts, are invented.4142 License: CC BY 4.0 (creativecommons.org/licenses/by/4.0) for43 all prose and exemplars; the bundled scripts (*.py) are44 released under the MIT License (full text in assets/kit/LICENSE).45 (c) 2026 Paul Hess.46 ============================================================47-->4849# SmartFolder Skill (v6.6.0)5051Turn the target folder into a **SmartFolder**: a self-maintaining navigation-and-knowledge layer52over the real files, so the user, other people, and future Claude sessions can operate in it with53full context — finding things by location, and drawing on synthesized knowledge that no single file54contains — without opening every file.5556## How this skill runs5758This is **interactive, customized work**, not a template application. The user will describe their59intentions and goals in their own words — treat that as the *requirements* and this skill as the60*method*. Expect an interview; the design is worked out together through the phases below, each61ending at a review gate.6263> **Design stance.** Only the invariants and safety rules below are fixed. Everything else is64> decided per folder through a needs diagnostic, guided by principles, three real precedents, and65> the bundled kit. Detailed specification of flexible decisions is deliberately avoided: being66> overly prescriptive about flexible design choices becomes *proscriptive* in implementation — it67> forbids better designs. Where this skill is silent, design from the principles and precedents68> rather than asking for a rule.6970**Two kinds of bundled content, never to be confused.** `assets/kit/` is the **kit**: working71exemplars and scripts that get **adapted and deposited into the user's folder** (Phase 5).72Top-level `references/` is the opposite — files **this skill reads on demand when a branch fires73and never deposits**: `references/DEPOSIT_SPEC.md` (the complete Phase-5 deposit specification),74`references/UPGRADE_PATH.md` (the full existing-SmartFolder upgrade path), and75`references/VERSION_HISTORY.md` (the full changelog). Nothing from `references/` ever lands76in a built folder.7778## Non-negotiables (safety — these override everything else)79801. **Nothing moves, gets renamed, or gets generated until the user approves a plan.** Staged work,81 review gates.822. **Back up first** (zip/tar the tree) before any move or rename. **Log every move/rename** to a83 `move-log.csv`. After moving, **verify by content hash against the backup** — not just counts.843. **Never delete.** Instead, move unneeded files to a single manual-delete folder at the root;85 one such folder per SmartFolder. What the staging rule86 protects is a **category, not a location**: staged content never re-enters the folder's87 knowledge layer — never read, quoted, reconciled against, or restored from. **One exception:**88 a single light manifest (`_README.md`), written at staging time by the session that staged —89 one line per item: what moved, when, why, where the surviving copy is — so the owner isn't90 emptying unlabeled files on trust. The separating test: the manifest may be consulted *only*91 to answer a question about the disposal itself ("is it safe to empty this? why is that in92 there?"); any other use, including answering anything about the folder's subject matter, is a93 violation of the rule, not an exercise of the exception. The manifest is not curated, earns no94 maintenance, and **dies with the contents** — when the owner empties the folder, it resets.954. **macOS bundles are atomic** (`.rtfd`, `.oo3`, `.key`, `.pages`, `.numbers`, `.goodnotes`,96 `.webarchive`, companion `*_data` dirs, and kin): rename if needed, never recurse into or write97 inside.985. **Never clobber existing guides, indexes, `CLAUDE.md`, or `AGENTS.md`** without explicit OK. If SmartFolder99 scaffolding already exists, this is an **upgrade**, not a build (see *Existing SmartFolders*).1006. **Don't modify file contents.** Only add guide/derived files and (if approved) move/rename. If a101 folder is shared or off-limits, work from a copy.1027. **Never guess.** Flag anything you can't confidently summarize; a confidently wrong summary or103 synthesis is worse than none.104105*One procedure in this skill reaches the network — the monthly version check this skill deposits106into every folder it builds (Phase 5); everything else is local files. The check degrades to107silence when the network doesn't answer, so no folder ever depends on connectivity.*108109## The invariant core (every SmartFolder shares these)110111**The tier model — read top-down, stop when you have enough:**112- **Tier 1 (resident):** one resident root manual — `CLAUDE.md`; in the dual profile it exists as113 two byte-identical files, `CLAUDE.md` and `AGENTS.md` (see *Root files by agent population*) —114 the only content that auto-loads every session and115 survives compaction. Protocol + conventions + behavioral rules + a thin top-level orientation.116 Keep it lean (under ~150 lines); detail lives in the files it points to.117- **Tier 2 (on demand):** a `_README.md` in each meaningful folder — a **local router** describing118 its own folder and mapping its immediate children. Tiny/leaf folders fold into the parent's guide.119- **Tier 3 (on demand):** derived, digested knowledge — per-file sidecars (`<stem>_Summary.md`),120 folder syntheses (`_Synthesis.md`), and whatever status surfaces the folder's needs call for121 (boards, decision logs, indexes, hubs). Which of these exist, and in what proportion, is the main122 design decision (see *The diagnostic*).123- **Raw files:** the bottom of the waterfall — opened only when a digest won't do.124125**Navigation is by location, not a central index.** The root file states the protocol — *before126working in or answering about a folder, read its `_README.md` first* — and each guide routes to its127own children. Nothing global to keep in sync. Only the root file is named `CLAUDE.md`; per-folder128guides stay `_README.md` (nested `CLAUDE.md` auto-loading is a Claude-Code-specific, after-the-fact129behavior — the explicit protocol is portable across products and predictable).130131**Root files by agent population (dial 7).** Single-agent folders keep one root `CLAUDE.md` and pay132none of what follows. Where the dial says other assistants may work the folder, use **guarded133duplication**: byte-identical `CLAUDE.md` and `AGENTS.md`, each carrying a one-line reciprocal134instruction — any change to one is applied to the other before the task completes. **`AGENTS.md` is135canonical on divergence**; repair by re-copying from it, and add a root-files-differ check136(`cmp AGENTS.md CLAUDE.md` — silence means identical) to the folder's integrity script, or to its137runbook verification list if it runs none. **Never assemble either root file with `@` imports:**138some surfaces inject `CLAUDE.md` verbatim with no import expansion, so an imported manual arrives139empty — no error, no trace. Why duplication: the project-root file is re-read from disk and140re-injected after compaction, which conversation content is not, so a real file — not a pointer to141one — is what survives a long session on every surface; and duplication's failure mode, divergence,142is mechanically detectable where a stub's mid-session staleness is not. In dual folders, deposited143wording is agent-neutral ("ask your AI assistant"), lock files record the holder "via144<assistant/surface>", and nothing relies on HTML comments being invisible — other agents read them145as content. The root file is context, not enforcement: deposited wording never promises compliance.146147**Every derived surface is dated and ranked:**148- Every guide, synthesis, and status surface carries an **`As of [YYMMDD]`** line.149- **Recency wins:** when two dated surfaces disagree, the more recent as-of date wins.150- **Raw beats derived:** a synthesis or summary is AI interpretation; the raw file wins on conflict.151- **The filesystem beats the map:** a live directory listing outranks any guide's file map.152153**Derived knowledge surfaces — where the added value lives.** The derived layer holds knowledge154that no single file contains and that would otherwise require tedious browsing of many files.155**Synthesis (`_Synthesis.md`) is the archetype**: it exists only where the whole exceeds the parts,156correlating, combining, and commenting across a folder's files to yield the holistic story — arcs,157patterns, cost roll-ups, cross-system connections, recurring failure modes. Synthesis has siblings,158distinguished by the kind of tedium they remove: a **status board** (currency over time — one dated159line per workstream plus its next gate); a **longitudinal tracker** (one subject — a medical issue,160a negotiation arc, an easement — threaded across many files and years); a **decision log**161(append-only dated record of what was decided, with sources); **cross-folder maps and hubs**162(maintenance calendars, vendor directories, sensitive-info maps, entity indexes); and **computed163views** (dashboards, charts, extract tables built from the structured layer). The taxonomy is open —164invent the species this folder's questions call for.165166All species share one discipline: an `As of [YYMMDD]` header; claims anchored in-narrative ("through167[date]…"); stated **provenance** (what it was derived from, as of what state — which doubles as the168staleness test) and a **decay condition** (when it might begin to be wrong); a label as derived AI169analysis (raw wins); and the one-line breadcrumb *"To refresh: ask your AI assistant to update170this."* The discipline belongs to **every** derived surface, Tier-2 guides included: a171`_README.md`'s descriptive front matter carries its as-of line, provenance, and decay condition172like any Tier-3 species. The behavioral rule — **offer to refresh any derived surface materially173behind its sources before relying on it** — lives once, in the root file, not in each file.174175**Write forward, not backward (live surfaces).** A live surface — one whose subject is still176moving: a board row, a README's front matter, the synthesis of an ongoing system — leads with the177present: current state + what's next, one screen, written from now looking forward. The test: a178newcomer's first screen answers "where do things stand?" without summing dated patches. Refreshing179means **rewriting the front matter, not appending a dated delta** — appending is the writer's cheap180path, but it shifts the cost onto every future reader. Small deltas may accrete between rewrites;181at a **chapter boundary** (a close, a kill, a pivot, a replacement) the surface is rewritten182state-first and the accumulated narrative is **demoted whole** into a labeled history section or a183sealed, dated index, with one pointer from the front matter — never deleted or summarized away184(that is what makes rewriting safe). Tripwire: front matter carrying more history than present185state is a boundary in disguise — a rewrite is due. Archival syntheses of completed arcs already186comply: their "present" is the finished story. Deposit this rule in each SmartFolder's root187`CLAUDE.md` (procedure in the runbook) — accretion is a maintenance-time failure, and the skill188won't be there.189190**Sidecars (`<stem>_Summary.md`) are caches, not commentary.** A sidecar pays rent when the raw191file's read-cost × consultation-frequency is high. Typical triggers: long or dense PDFs and192transcripts (re-reading a 60-page transcript can cost a session 100K+ tokens); scanned, OCR'd, or193handwritten material where extraction is slow or error-prone; formats Claude reads poorly or not at194all (the sidecar is then the only machine access); authority documents — contracts, reports, rulings195— whose exact terms will be asked about repeatedly (capture the key terms plus last-mile pointers:196"signature page is p. 14"); files whose payload is visual; and files a synthesis leans on, where the197sidecar doubles as the synthesis's provenance anchor. Skip routine items, media dumps, and anything198the folder's README or synthesis already covers. Sidecars move with their file.199200**Self-orientation from anywhere:** each `_README.md` opens with one line noting it is part of a201SmartFolder whose protocol lives in the root `CLAUDE.md` — so a session that mounts a subfolder can202still find the system.203204**Proportionality:** every artifact must pay rent — real signal against its maintenance cost. No205rote guides, no unwarranted syntheses, no machinery a folder's needs don't justify.206207**Self-containment:** the finished SmartFolder carries its own maintenance payload (see Phase 5).208After the build, this skill is only needed to seed *new* SmartFolders — never to maintain this one.209210**Naming (the default house convention — adapt to the folder's own tradition where one exists):**211- **Dates lead**, as `YYMMDD` or `YYMM`, no dashes; `YYYY` only when just the year is known. Decode212 2-digit years by century (≥90 → 1900s). If the archive spans the century boundary or the 1980s,213 raise it in Phase 2 — string sorting breaks across centuries — and agree on handling.214- **PascalCase** within one concept, **underscores** between concepts; **theme-first** so like items215 cluster: `DATE_Type_Specifier.ext` (e.g. `2312_WaterReport_FairfaxCounty.pdf`).216- Where a name is vague or wrong, **peek inside and name by real content**; add missing extensions;217 fix problem characters (colons, `#`, hidden/non-breaking spaces, trailing spaces). Bulk-rename218 with globs, not hardcoded names, and verify each rename happened.219- Bulk media/photo dumps: batch-name, don't curate each; describe the group in the guide.220221## The diagnostic (design through interview, not menu)222223Before proposing scaffolding, learn the folder's needs — from the user's stated intentions, from224Phase-1 exploration, and by asking (AskUserQuestion works well here). The dials:2252261. **Writers and users.** Who adds or edits files — Claude only, one human, several humans? Via a227 sanctioned intake path or directly? How technical is each? **And whose files are they?** If228 this reveals the minority case — the folder holds files of an owner who is not driving or229 coordinating the build — suggest winning the owner's buy-in before the plan executes: a warm,230 non-technical one-page note saying what will move and why, with nothing deleted (the kit's231 `Example_Owner_Letter.md` models the shape and tone). Most folders are built by, with, or under232 the authority of their owner and pass through with no mention — this is a conditional offer,233 never a standing step. Usage changes over time, so the deposited growth menu carries the same234 trigger forward. A second conditional offer hangs on the same dial: where several people will235 use the folder across sessions, offer the **session-flags register** (the kit's236 `Example_SESSION_FLAGS.md`) — a person-addressed notification surface for "next time X is237 here, tell or ask them Y," whose content and state live entirely in the register while the238 root file carries only the trigger. Collaborative folders only — a single-writer folder is239 never shown it; the deposited growth menu carries the same conditional row forward, so a240 folder that grows into multi-user life can reach it later. And where the folder is shared over241 a cloud-sync service, state the offline-availability requirement here, while the multi-writer242 arrangement is being designed: **every collaborator's machine** must hold the folder offline —243 "Make Available Offline" (Dropbox), offline access (Google Drive), or the service's244 equivalent — or that person's sessions read placeholders. A per-machine setting, never a245 one-time folder setting.2462. **Change velocity.** Archival (rarely changes), slow-drip, or live and fast-moving?2473. **Dominant question type.** What will people mostly ask here — *navigation* ("where is X?"),248 *wisdom* ("how does this work? what matters? what's due?"), or *status* ("where do things249 stand?")?2504. **Enforcement posture.** Should integrity machinery *offer* (advisory, non-blocking) or *gate*251 (hard checks before work proceeds)?2525. **Authority model.** Raw files only? Hand-authored primary notes that must stay primary and be253 kept in sync? Volatile facts needing a single dated source-of-truth surface?2546. **Audience and tone.** Who reads the guides — and how plain must the language be?2557. **Agent population.** Will AI assistants other than Claude work this folder? The relevant256 population is assistants that work *in folders*, not chat alone. Ask in plain product terms,257 without assuming the user knows what any of these are: *"Will this folder be used only with258 Claude (Cowork or Claude Code), or also with other AI tools that work in your folders —259 OpenAI's ChatGPT Work or Codex, Google's Gemini (Spark or CLI), Microsoft Copilot, Cursor, or260 something else — now261 or someday?"* Only Claude → single profile: one root `CLAUDE.md`, none of262 the dual tax. Anything else → the dual profile (see *Root files by agent population*). If the263 user is unsure, choose single: converting later is one copy plus the reciprocal lines.264265**Allocation principles (the actual design law):**266- **Spend the derived-layer budget where the dominant question lives.** Navigation-heavy → rich267 `_README.md` coverage. Wisdom-heavy → syntheses (and perhaps a one-page hub). Status-heavy →268 boards, decision logs, indexes, sidecars.269- **Control machinery scales with write-traffic × writer count:** none → a casual tripwire →270 intake discipline with locks and hard integrity gates. Never more than the traffic justifies.271- **File-map richness:** enumerate files only where names can't speak for themselves, and scale272 enumeration down as change velocity rises — a good renaming pass and a file map are substitutes;273 in a fast-moving folder, annotate and route rather than list.274- **Tone to the least technical reader** who will use the folder.275- **Invent freely; skip freely.** Derive machinery this list doesn't name if the needs call for it;276 omit anything here that doesn't pay rent. Confirm significant inventions with the user before277 building.278279## Precedents (case law, not templates)280281Three real SmartFolders built with this method. Note what they share (the invariant core, exactly)282and how each spends its budget differently — driven by its needs, not by a feature list.283284- **The Archive** — a 22-year, ~6,700-file family records archive; one technical user; near-zero285 change velocity; dominant question "where is X?". Allocation: a `_README.md` in every meaningful286 folder with full annotated file maps (stable, because content rarely changes); only two syntheses,287 placed at genuine arc points (the whole academic record; a school-search saga); no sidecars, no288 locks, no boards. A generator script emits guide scaffolding and stamps content-hash markers so289 re-runs preserve hand edits; a documented periodic sweep handles intake.290- **The Advisory folder** — estate/property records shared with a non-technical owner; owner edits291 files directly; dominant questions operational ("what's due? how does this system work?").292 Allocation: ~40 per-system syntheses seeded from the owner's hand-authored MASTER notes (which293 stay primary, with a stated sync protocol), plus a one-page Operations Hub (maintenance calendar,294 vendor directory, sensitive-info map). Integrity is a **non-blocking daily tripwire** — a watcher295 that detects direct changes and *offers* dispositions, never gates. Warm, jargon-decoded tone;296 gotchas storytold; polished owner-facing PDFs at the root.297- **The Operational folder** — a live, multi-user deal workspace shared on Dropbox; several writers;298 daily change; dominant question "where do things stand?". Allocation: a one-screen status board,299 per-initiative decision logs and document indexes, and per-file summary sidecars on most documents300 so raw files rarely need reopening. Control machinery is **hard**: all new content enters through301 an inbox workflow under a courtesy lock; a content-hash manifest with a session-start scan and a302 review queue makes colleague edits surface within a day; prescriptive tone; explicit lifecycle303 (closed initiatives archived with closing memos).304305**License clause:** these are precedents, not menus. Cite them, interpolate between them, depart306from them — the test is whether the resulting scaffolding serves *this* folder's diagnostic, not307whether it resembles an example.308309## The companion kit (bundled — `assets/kit/`)310311Working artifacts drawn from the three precedents ship with this skill: the integrity and312change-tracking scripts, a guide generator, an inbox workflow and lock file, a drift-disposition313matrix, and growth menu / owner letter / owner guide / status board /314decision log / review queue / operations hub / synthesis / guide / sidecar exemplars. Integrity315machinery comes in **three species** — the advisory tripwire (offers), the hard gate (blocks), and316the generator's content-hash markers (protect generated guides from regeneration) — and the matrix317is the hard gate's companion reference, not a rung the advisory tier is climbing toward. **Start from318`assets/kit/00_KIT_README.md`**, which maps each artifact to the diagnostic dials that warrant it.319That README's table is the **index** — it answers whether an artifact is warranted; the exemplar is320the **specification of what the artifact is — never of what yours must be**. Open the exemplar321before authoring any surface it models — a step, not a recommendation; per artifact, at authoring322time. Then decide freely: adopt, adapt, or depart — the exemplar is a well-built guide from one323folder's life, and *this* folder's diagnostic, profile, and owner govern what is actually built.324Where your departure changes a form a reader would notice, say so and why, at the point of the325decision.326Kit artifacts are **starting points to adapt, never to transplant wholesale**: the markdown327exemplars are fictionalized (real shapes, invented content), the scripts' sample configuration and328example content are likewise invented, and the scripts need their paths, conventions, and329ignore-lists adapted to the target folder. Scripts destined for the target330SmartFolder are copied into its meta folder in Phase 5.331332## The build (phases — each ends at a review gate)333334**Phase 0 — Intent.** Absorb the user's stated goals and constraints; confirm scope (this folder335only, or siblings too?). Touch nothing.336337**Phase 1 — Explore and report.** Walk the tree: folder/file counts, depth, biggest areas,338file-type mix, the naming/date conventions actually in use (they may differ per subfolder — honor339detected conventions rather than imposing one rule everywhere). Detect existing instruction files340(`CLAUDE.md`, READMEs, `AGENTS.md`, `.claude/`) → route to the upgrade path. Flag oddities that341change the plan: problem characters, no-extension legacy files, scanned PDFs with no text layer,342locked files, mislabeled files. On a cloud-synced path (Dropbox, Google Drive, or similar), reads343that stall, fail, or return empty content usually mean online-only placeholders, not broken files344— name the fix rather than diagnosing file-by-file: the folder needs "Make Available Offline"345(Dropbox), offline access (Google Drive), or the service's equivalent, set per machine. Note346synthesis candidates — folders whose files together tell a347story — and folders that are mere piles of like items (no greater whole; skip).348349**The front-door gate — after the look, before any commitment.** When this skill fired on a plain350organize-request — a folder to organize with no scheme the user has already chosen — do not351commit silently to either path. Phase 1's mere-piles skip applies first: twelve holiday photos352never hear the offer. Otherwise offer the method, once, in plain terms: *"I have to understand353this folder to organize it well — want me to write down what I learn while I'm in here, so the354next person or session doesn't start over?"* The fork is explicit and both paths are nameable —355**build** (continue into Phase 2) or **just-organize** (do the requested work well and stop). A356declined offer deposits nothing: no scaffolding, no marker, no record of the decline — whether to357raise it again is ordinary conversational judgment. A request that supplied its own scheme was358never this gate's business: execute it, no offer.359360**Phase 2 — Diagnose and decide.** Run the diagnostic interview. Then propose, for the user's361approval: the **profile** (dial readings + the allocation they imply + rationale), the362reorganization scope (guides only / group into chapters / full restructure with renaming), the363naming convention, and a **dry-run plan** showing where every folder and loose file lands and which364folders get which derived surfaces. While naming is on the table, mention that at close-out the365skill will suggest appending `SmartFolder` to the folder's own outer name (Phase 6 makes the366offer) — so it is no surprise later.367368**Phase 3 — Sample.** One chapter end-to-end. Judge it together on whether the guides and any369synthesis are *genuinely useful* — not just present.370371**Phase 4 — Apply.** Execute moves/renames with logging and hash verification; author guides and372syntheses **from real contents** — never auto-fill filler prose. Size the approach to the job: a373generator script for scaffolding on large trees (prose in a separate content layer; content-hash374markers so re-runs preserve human edits; hand-written guides just carry their as-of line), direct375writing on small ones. At scale, fan out parallel sub-agents on disjoint scopes with their own move376logs and required integrity reports; keep judgment calls and shared-file writes single-threaded.377378**Phase 5 — Deposit the infrastructure.** The SmartFolder must be self-contained: after this379phase, maintenance never needs this skill. **Read `references/DEPOSIT_SPEC.md` — the complete380deposit specification, bundled in this package — in full before authoring any deposit, and reopen381it whenever Phase 5 resumes after a session boundary** (this stub survives compaction; the382reference does not). The list below is the index, never the spec:383- the root **`CLAUDE.md`** — and its byte-identical **`AGENTS.md`** twin in the dual profile;384- the four **close-the-loop** rules;385- the **session-boundary prompt** and the root manual's *Session boundaries* section;386- the **maintenance procedures** — consolidated in a runbook by default, distribution licensed387 with the arrangement recorded in the recorded profile;388- the **recorded profile**, any **adapted kit scripts** and generator, **move logs**, and the389 **backup manifest**;390- the **growth menu**;391- the **retained kit** — the whole of `assets/kit/`, byte-for-byte, a stable-named readable392 subtree in the meta home: the menu's implementation library;393- the **version baseline** — recorded always; the `.skill` package deposited when already in394 hand, never procured — carrying the monthly version check;395- the **developer-feedback offer** at build close-out, composed only on acceptance;396- the **version-upgrade review**, deposited among the maintenance procedures.397398**Phase 6 — Verify.**399- Coverage invariant: every meaningful folder has a `_README.md` or is explicitly covered by its400 parent's; no filler guides or unwarranted syntheses crept in.401- Root `CLAUDE.md` is lean, loads as project instructions, states protocol + precedence + refresh402 rule; orientation links resolve.403- Every derived surface carries its as-of line, provenance, and a decay condition; flag any derived404 surface whose sources are newer than its as-of date.405- No derived files inside bundles or trash; internal links resolve; content-hash check against the406 backup shows no loss; spot-check summaries and syntheses against raw contents.407- Dual profile only: `cmp AGENTS.md CLAUDE.md` is silent, and a **parity probe** passes for every408 agent that will work the folder — plant unguessable content in the root files, ask each agent to409 quote it back, check for **exact match**, and give explicit permission to answer "I see none."410 Never ask an agent to confirm it "has the instructions": a session without them will confabulate411 a plausible answer rather than report absence.412- The root file's close-the-loop list names exactly the surfaces that fail the locality test — no413 more, no fewer — swept against the **entire** surface inventory, with every external-state414 surface on it by definition; and every listed surface states its own decay condition.415- Prescriptive, dateless files (the root manual, the runbook, deposited READMEs) carry no416 point-in-time state that a status surface owns; **spot-check a sample** of the source-pointered417 constants that remain against their sources — a sample, not an audit; the pointer's real work418 happens at edit time.419- Sweep the deposited surfaces for capability language — "is blocked", "cannot", "typically420 can't", "available", and kin. **The sweep is a finder, not a verdict**: judge each hit — is the421 capability the rule's genuine **precondition** (keep it, and it must state its false branch), or422 the **justification** for a rule that applies regardless (strike the claim, keep the rule)? It423 must not fire on legitimate conditionals — dual-profile rules, conditional registers, and424 degraded modes are correct as written.425- The root's *Session boundaries* section exists, one line per active duty, each pointing at a426 procedure file that resolves; the deposited `VERSION_BASELINE.md` carries the check procedure,427 both URLs, and the `Last checked` stamp — and where the folder runs integrity machinery, the428 baseline is a sanctioned write target.429- The **maintenance procedures exist and are findable where the recorded profile says** (a430 consolidated runbook, in most folders); the meta folder holds the recorded profile, growth431 menu, version baseline, and retained kit; the maintenance loop works without this skill.432- The retained kit is **byte-identical to this package's `assets/kit/`**, carries no generated433 guides, sidecars, or syntheses inside it, sits on the drift machinery's ignore-list where any434 runs, and **every growth-menu pointer naming a kit artifact resolves into it** — no package,435 installed skill, or network required.436437**At close-out, once — the outer-name suggestion** *(an offer, deliberately not a verification438check — nothing about it is checkable, and a check that always passes trains people to ignore the439list)*: recommend the user append **`SmartFolder`** to the folder's own name — `Acme Consulting` →440`Acme Consulting SmartFolder` — so a built folder is recognizable from outside any session: in a441file browser, a backup job, a list of connected folders. A space separates by default; the442folder's own separation convention wins (`Acme_Consulting` → `Acme_Consulting_SmartFolder`). Skip443the offer when the name already ends in the suffix, case-insensitively. **The name is the owner's,444and any rename happens only on their say-so.** In most environments the session cannot rename its445own root: the root folder is the handle the environment hands the session, not a file inside the446tree, and renaming it mid-session severs the reference the session runs on. There, the offer states447**both steps**, for the owner to carry out between sessions: rename the folder, then **re-point448whatever holds it under the old name** — in Cowork, re-select the folder; in Claude Code, update449the project's path; in any other assistant, whatever it uses to locate this folder — or a future450session will not find it. **Where the environment does let the session rename the root and re-point451its own reference safely, it may offer to do that itself** — verify the connection afterward, and452the two-step instruction above remains the fallback. Offer once; accept a no without argument and453do not re-raise in this session; record nothing — the outer name is the owner's, and out of this454folder's scope once built.455456## Existing SmartFolders (the upgrade path)457458When Phase 1 detects SmartFolder scaffolding already present — a root `CLAUDE.md`/`AGENTS.md`,459`_README.md` routers, a meta folder with a runbook or version baseline — this is an **upgrade,460not a build**. **Read `references/UPGRADE_PATH.md` — the full upgrade path, bundled in this461package — before proposing anything.** It carries the version-against-version review route, the462accretion audit, and the standing repairs a session offers because deposited machinery never463self-heals (the version check, capability-resting rules, pre-identity flags registers, the464growth-menu sentence, the outer-name suffix). The non-negotiables bind on this path too, and the465folder's recorded profile — not this skill's defaults — governs unless the user says otherwise.466467## Working style468469Use a task list; keep updates concise; show samples before mass-applying; ask before underspecified470work. When new content arrives later, any session should be able to run maintenance from the471deposited procedures (the runbook, in most folders) — add guides for new folders, refresh stale472guides and syntheses while preserving473manual edits, and re-run the verification steps — without this skill installed.