3.1 start-session

Documents start-session 4.1.0 as it ships in the Pay de Manzana 1.3.1 package.

In one sentence

start-session prepares every work conversation: it finds out what session type it is, loads only the context that type needs —sending readers in parallel, one per file, that bring back facts with citations— and hands you a line that says what it loaded, which machine you are on and what to watch.

When to use it and when not to

Use it at the start of any session. Phrases like "load context", "start session", "let's pick back up" or "catch me up" trigger it, and the most precise way is to declare the session type in your first message.

Mid-session, for a single source, tell it "bring <source>" (details in the master manual, §3.1, "Bring…" mid-session).

It does not write to your environment. Starting is reading. The only possible write is noting the machine you are on, and only if you give it the name. It also does not retire projects that have gone a while without moving: it flags them and nothing more.

It does not start without your master folder. If it is not connected to the conversation, it asks for it; without it, it does not continue.

The seven session types

Types 0 and D only read the core and report; the others also send loaders, reconcile what they bring back and then report.

How to declare the type

Write the word Session followed by the type in your first message. The full form is:

Session <TYPE> · <domain> · <project> · <assignment> · logbook: <reason>

Only the type is required; the rest is optional and works just as well separated with · or said in prose. Words that count as a type: OVERVIEW, PROJECT, ASSIGNMENT, MECHANICAL, META, COORDINATION. There is one more, DIRECTED: it counts as ASSIGNMENT if you name an assignment that exists as a file, and as PROJECT if not.

Examples (the names are made up):

• Session PROJECT · Sales · Weekly report — works on that project.
• Session PROJECT · Weekly report · logbook: format change — also loads from the logbook the entries that touch that reason.
• Session ASSIGNMENT · clean-catalog — executes that assignment; it finds it even if you don't name a project.
• Session COORDINATION · Sales — reviews the status of the domain's projects.
• Session META — for working on the environment; this type only exists if you declare it.

If you don't declare it

It infers the type from what you ask, trying in this order and keeping the first one that applies:

1. You name an assignment that exists as a file → C.
2. You name several projects or assignments to manage them, not to execute them → F.
3. You name a project → B.
4. You ask for an overview, your pending items or what was left open → A.
5. You ask for a mechanical task with no project memory → D.
6. There is no signal —a greeting, a question with no subject— → 0.

Type E is never inferred. When the type was inferred or came from a default, the report suggests that you declare it next time with "Session <TYPE> · <project>".

3.2 close-session

Documents close-session 3.2.0 as it ships in the Pay de Manzana 1.3.1 package.

In one sentence

close-session saves what the session left behind: it writes a record of what happened and hands it to three fresh writers who move the new knowledge into the corpus, remove from the inbox what has already been used and update the logbook and each project's memory, each at its own level; at the end it leaves you a title, a short report and a stamp for a closed session.

When to use it and when not to

Use it when you finish, with phrases like "close the session" or "we're done", or when you say goodbye. It also triggers on its own when a durable fact changes mid-session —your profile or a project's status.

It runs in one of three modes:

Don't use it to migrate an old project to the current form: that belongs to start-project. The close-out writes to the project in whatever form it has.

3.3 start-project

Documents start-project 3.1.1 as it ships in the Pay de Manzana 1.3.1 package.

In one sentence

start-project turns a work idea into a project with a clear objective: it interviews you until the objective is firm, creates the project folder, writes its central document (project.md), enters it in the project index and leaves its instruction box ready.

When to use it and when not to

Use it when you are about to begin work that deserves its own folder and memory. Say something like "start a project", "new project" or "set up this folder".

Don't use it to create a domain (a new organization or area, such as your company or your Personal area). If you ask it to, it tells you so and sends you to pay-de-manzana ("add a domain").

It does not start anything if you are not there. If you invoke it in a task that runs on its own, it does not invent the objective: it leaves an assignment with what it gathered in the domain's _Inbox/ inbox and lets you know. The objective always comes from you.

3.4 capture-knowledge

Documents capture-knowledge 2.2.1 as it ships in the Pay de Manzana 1.3.1 package.

In one sentence

capture-knowledge reviews what the session learned, keeps only what will be useful beyond the current project and writes it into the domain's Knowledge Corpus, following the rules that corpus declares in its SCHEMA.md; the agent writes and you curate and decide.

When to use it and when not to

When the session closes, close-session invokes it, as the lock on the close-out: nothing else is written until it is resolved. You don't need to ask for it.

On its own, at your request: "distill the session", "send this to the corpus". It also runs on the spot when the work needs to link a new entity that is not yet in the corpus.

It does not write the logbook or project memory: those belong to close-session. It only writes to the corpus.

It does not create or review your profile. If something it learned describes you, it does not write it to the corpus or to your profile: it leaves it as an observation pending your confirmation.

3.5 write-assignment

Documents write-assignment 3.0.1 as it ships in the Pay de Manzana 1.3.1 package.

In one sentence

write-assignment drafts an assignment: the record of a job that cannot be done at this moment, written so completely that any future session can start it without anyone explaining anything again. It saves it in the owning project's <Project>/_Memory/assignments/<slug>.md, or in the domain's _Inbox/ inbox if it doesn't have a project yet. It writes it; it does not execute it.

When to use it and when not to

Use it when you want to leave a job assigned for later. Say "make me an assignment" or "queue this". You also use it for two more things on an assignment that already exists: advancing one in draft to ready (answering its pending questions) and re-thinking one that is misaligned (one that fell behind because the objective changed).

Don't use it to do the work. When it creates the assignment it does not execute it: it leaves it ready in the queue for another session to pick up.

One topic at a time. It does not open several assignments at once unless you ask, and it respects the handling preferences you have in _Memory/profile.md in your master folder.

3.6 question-user

Documents question-user 2.0.1 as it ships in the Pay de Manzana 1.3.1 package.

In one sentence

question-user questions you about a plan, an idea or a decision until nothing is left assumed in silence, and at the end hands you a record of what was decided, ready to paste wherever it is needed. It does not write files: the result is the shared understanding in the conversation and the record; whoever invoked it decides where it goes.

When to use it and when not to

Use it before committing to something that is not yet clear. Say "question me", "interrogate me", "stress-test this idea" or "before we start, ask me".

Don't use it for a loose execution question (for example, "do I save it as PDF or Word?"). That one gets answered and that's it; this skill is for a whole plan or decision.

Other skills also call it. For example, write-assignment invokes it when an assignment has three or more open questions left after the first round. Its two declared outputs are write-assignment (to turn what was decided into an assignment) and capture-knowledge (to save what is useful to other projects).

What it can do while it questions you is read and search your files and the folder you have connected, launch search subagents, consult the web and ask you questions with options to choose from. Those are the only tools it declares; it edits nothing.

3.7 maxwell

Documents maxwell 3.0.1 as it ships in the Pay de Manzana 1.3.1 package.

In one sentence

maxwell audits a deliverable against the objective of its assignment before it reaches you: a fresh reviewer —a subagent that did not do the work and does not alter anything— classifies it with a fixed vocabulary, and Maxwell gathers what is needed, records each round and reports to you. It only lets through the work that meets its objective.

When to use it and when not to

Use it when closing an assignment, when you want to know whether something is ready to hand over, and always for long or delicate work. Say "run it through Maxwell" or "is it ready yet?".

Don't expect it to fix things. The reviewer does not alter anything, and Maxwell does not repair either: the findings go back to the session that did the work so that it can correct them.

Don't expect a yes out of courtesy. If something could not be tested, the ruling says so (COULD NOT VERIFY); it does not pass it as good.

3.8 pay-de-manzana

Documents pay-de-manzana 1.3.2 as it ships in the Pay de Manzana 1.3.1 package.

In one sentence

pay-de-manzana brings your Cowork environment to its current form: in INTEGRATE mode it sets it up from scratch, adds a domain, updates it to the new package or restores what is missing —and it is the only mode that writes—; in REVIEW mode it does exactly the same analysis and tells you what it would do, without touching anything.

When to use it and when not to

Use it with phrases like these:

You can also start it by its name. If your phrase doesn't make the mode clear, it asks you just once: "Review only, or fix too?".

Requirement: the master folder (your environment's folder) has to be connected to the conversation, in both modes: to read always and to write in INTEGRATE. Without it, it guides you to connect it and does not start.

Don't use it to:

• Install, update or remove skills. It brings your environment up to date, not your skills: that is always a step for you in the app.
• Migrate a project's project.md. start-project does that, project by project; this skill gives you the line to open that session.
• Set up Drive sync. It doesn't set it up; if something about the sync gets in the way, it works locally and lets you know. Working without sync is a valid state.
• Review your profile in the middle of other work. The profile module only runs in a process dedicated to it (the setup, a migration or when you expressly ask for it), never inside a session with another objective.

3.9 develop-skills

Documents develop-skills 3.3.0 as it ships in the Pay de Manzana 1.3.1 package.

Who this chapter is for. develop-skills is a skill for whoever builds or adjusts the environment, not for daily use. You will see it work when you write a skill of your own or fix one from the package; if you only use the environment for your work, you don't need it. The why of each rule is in the "topics" view and in the master manual.

In one sentence

develop-skills takes a skill through its whole cycle —design, draft, freezing, delivery, installation and registration— with gates that prevent writing before you approve the design, numbering a version before you say "freeze it" and delivering a package that nobody else reviewed.

When to use it and when not to

Use it whenever the session is going to create, edit, review, version, package or audit a skill, even if the assignment doesn't ask for it. It loads together with skill-creator. It is enough to say something like "let's make a skill for…", "fix this skill" or "package the skill".

Don't use it to write the text itself. How an instruction is written —what goes in, what stays out, how long it is— is set by write-for-agents, which this skill loads. develop-skills handles the cycle: stages, version, gates, packaging and delivery.

It does not install anything. It hands you the package with its button; the click is yours.

3.10 write-for-agents

Documents write-for-agents 1.1.1 as it ships in the Pay de Manzana 1.3.1 package.

Who this chapter is for. write-for-agents is a skill for whoever builds or adjusts the environment, not for daily use. You will see it work when you write or fix an instruction box, an assignment, a memory or a skill of your own. The why of each rule is in the "topics" view and in the master manual.

In one sentence

write-for-agents is the standard for writing and reviewing every text that an agent reads in order to execute: it says what goes in, what stays out, how long it can be, and it delivers each review with the corrected text and a findings sheet with file and line.

When to use it and when not to

Use it when writing, reviewing, slimming down or auditing a skill, an instruction box, an assignment or a domain or project memory, and before accepting a skill's description as good. Other skills in the environment load it on their own before writing those texts (for example, start-project and develop-skills).

Don't use it for documents that people read: a manual like this one, a report or meeting minutes are not instructions for an agent.

Don't use it to package or version. The packaging and versioning mechanics live in develop-skills.

3.1 start-session

Why it exists

Loading too much costs you and causes confusion. A session that is only going to transcribe an audio file doesn't need the logbook or the project index; one that is going to decide a project's direction does. If every session read the whole environment, it would pay to read what it doesn't use and mix what is current with what doesn't apply. That is why there are seven session types, and each one opens only its own sources. What the type's table doesn't name doesn't get opened; to know what is in a folder, listing it is enough, no need to read it.

Cheap readers that bring back only what matters. The big files —the logbook, the corpus, the domain sheet— are not read by the main window. They are read by a loader: a read-only subagent that answers fixed questions for the session type and returns facts, each one with the file and the line it comes from. No citation, no fact. That way the window gets a few verifiable lines instead of thousands of raw lines, and all the loaders run at the same time.

Every piece of data has an owner. When two sources say different things, one isn't picked silently: the source that declares that piece of data wins (the project's for its status, the profile for who you are), and the contradiction is reported to you with both citations so you can fix the wrong source.

The date and the machine matter. The system clock comes in UTC time, which in the late afternoon or evening is already a day ahead; everything stamped with a date afterward would come out wrong. And the machine that announces the start is the one the close-out uses to sign the session's logbook entry.

How to teach it

• The most common mistake is teaching it as «the one that reads everything at the start». It's the opposite: the one that decides what not to read. Teach it starting from the session types.
• Teach people to declare from day one. «Session PROJECT · <project>» in the first message saves the inference and its warnings. Loose phrases («load context», «let's pick up») work, but the type ends up inferred.
• Teach people to read the report line: date, machine, type, «Loaded» with its N of M, and the warnings. Whoever can read that line knows whether the session started well.
• Suggested demo: start the same conversation twice with a sample project —once with «hi» (type 0) and once with «Session PROJECT · <project>»— and compare the two report lines. Then ask «bring the logbook for <question>» and show how it gets added to «Loaded».
• Check questions: «What is the difference between a B session and a C session?», «Why isn't the E type inferred?» and «What does corpus 40 of 212 mean in the report?».

3.2 close-session

Why it exists

What isn't saved, the next session doesn't know. Every conversation starts blank; the only thing that carries over from one to the next is what was written in the master folder. The close-out is the step that writes it.

The window reports; others write. The conversation that did the work knows what happened, but it carries all the noise of the session. So it doesn't write to the corpus, the logbook or the indexes: it drafts a record and hands it to three writers that start fresh, with no material beyond that record. What isn't in the record doesn't exist for them, so the record is written first and with care.

A decision of yours is not paraphrased. If the record summarizes in other words what you decided, the next session obeys the summary, not your decision. That's why decisions go in verbatim: paraphrasing a decision repeals it.

Each piece of data at a single level. The detail lives at the lowest level that applies —the project— and only its status, one line and a pointer go up. If the same progress were written in the logbook and in the project, sooner or later they would say different things.

Some documents don't change without you. Your profile, the list of domains, the instruction boxes and the domain sheets govern every session. The close-out doesn't edit them: it proposes the change and waits for your approval.

The inbox is not a workplace. In _Inbox/ only what nobody has touched should remain; that way, when you open it, what you see is exactly what is pending.

How to teach it

• The most common mistake is teaching it as «the one that summarizes the session». Teach it as the one that distributes: the window writes a record and three writers put each thing in its place.
• Insist on the record. Everything that doesn't make it in there is lost; that's why decisions go in verbatim and the inbox items used are declared.
• Explain the seal. Continuing to write after 🔒 SESSION CLOSED is not an error, but it reopens the session: the name changes to ✗ and the new material is saved as an addendum until it is closed again.
• Suggested demo: in a sample session, make an explicit decision, use a file from the inbox and ask «close the session». Then open the logbook, the project.md, the inbox and _Memory/intakes.md so they can see where each thing ended up.
• Check questions: «Why doesn't the window write directly to the logbook?», «What happens to an inbox file you only read?» and «Which documents never change without your approval?».

3.3 start-project

Why it exists

The objective decides whether a project succeeds; everything else is scaffolding. The folders, the index and the instruction box can be created in a minute and they don't make anything turn out well. What does is knowing what has to be true at the end, for whom, and how it will be measured. That is why the skill spends the session clarifying the objective, and leaves the folders for last.

The start is the moment of most context. When someone decides to begin something, they have in mind why, for whom, and what worries them. A week later, they no longer do. The skill takes advantage of that moment with a full interview, not with «one or two questions»: what isn't pinned down at the start costs much more to reconstruct later.

A central document that only instructs. Every session that works on the project reads its project.md in full. If that file piles up history —what was tried, what changed, who said what— every session pays to read what no longer governs, and the agent can confuse the old with the current. That is why project.md holds only current instructions; the history goes in another file that isn't loaded.

Each piece of data in a single place. What is true about you goes in global memory; what is true about the business, in the domain; what is true about the project, in its project.md. The levels below point to the ones above, they don't copy. If a piece of data lives in two places, sooner or later they contradict each other and nobody knows which one governs.

Three project types because they progress differently. A job that finishes in an afternoon, one that evolves over months and one that repeats forever are neither planned nor measured the same way. A short project is not an abbreviated complex one: it asks fewer questions and seeds a different document.

How to teach it

• The most common mistake when teaching it is presenting it as «the one that creates the folders». The folders are the least of it: teach it as the interview that sets the objective.
• Don't say «answer a few questions». They are the complete script; if the assistant expects two questions and eight arrive, it feels like something went wrong.
• Suggested demo: start a real short project live for someone in the group. Let the skill propose each answer and let the group correct it. Finish by opening project.md and the index row so they can see that the memory got written.
• Check question: «What is the difference between a short project, a complex one and a process one?», and «What is the countermeasure for?».

3.4 capture-knowledge

Why it exists

Knowledge has to outlive the project. What you learn about a supplier, a standard or a team while working on a project is useful later to other projects. If it stays in the project's memory or in the logbook, nobody finds it. The corpus is the place where that knowledge lives; projects and logbooks reference it, they don't copy it.

Not everything that was learned is knowledge. The acid test is one question: is it useful to a session of another project six months from now? If it is only useful to this project, it is context and already lives in its project.md or in the logbook.

A few good pages are worth more than many. A corpus that grows with everything that happened becomes as hard to consult as having no corpus. That is why the skill is selective: zero pages is a valid result.

Each organization with its own corpus, no crossovers. One organization's knowledge isn't consulted or written from another; personal material isn't mixed with business material.

The corpus sets the rules, not the session. Each corpus brings its own SCHEMA.md: which page types exist, which fields they carry and how they are written. The skill loads it before writing and doesn't invent anything outside it.

How to teach it

• The most common mistake is teaching it as «the one that saves everything from the session». Teach it as a filter: its main job is to leave out what doesn't belong.
• Teach the acid test with cases: «is it useful to a session of another project six months from now?». Bring three or four facts from a sample session and have the group decide which ones pass.
• Separate corpus from profile: what describes the person goes to the profile, and only with their confirmation; what describes the business or its entities goes to the corpus.
• Suggested demo: in a sample session, mention a new entity (a fictitious supplier) and ask «move this to the corpus». Then open the page, the index.md and the package's log.md to show the three writes and the three provenance marks.
• Check questions: «Why doesn't a project fact go to the corpus?», «Where does the uncertainty of a fact go?» and «What happens with something the session learned about you?».

3.5 write-assignment

Why it exists

Work that is left for later gets lost if it isn't written down in full. When a task is postponed, the context that made it clear stays in the session that thought it up. The assignment fixes it in writing so another session —another day, on another machine, with another agent— can pick it up and do it right.

Two components decide whether an assignment works: the objective and the open questions. Everything else —the header, the paths, the limits— is scaffolding around those two. A weak objective doesn't show when you write it: it shows when the agent who picks it up decides badly on everything the assignment doesn't cover. And an unanswered question that nobody wrote down becomes an assumption by the agent. That is why the skill spends the session on those two components.

The golden rule. An assignment moves to ready —that is, it can be executed— only when its open questions section is empty and its acceptance criteria are something you can verify in under ten minutes. If checking the result would take you an hour, the criteria are not well written.

Draft first, ask later. The skill builds the assignment with what it already knows and then asks you only what is missing. What it deduced it marks as deduced inside the text of the assignment, not just in its head: whoever picks it up later needs to see what you confirmed and what was assumed.

An assignment that doesn't push its project's objective must not exist. Within a project, each task exists to bring it closer to its objective. If you can't say which objective it pushes, the work is surplus, or belongs somewhere else, or the project's objective is already stale. That is why the skill checks this before writing a single section, and if it doesn't pass, it doesn't write the assignment.

Each type of deliverable has its standard, and that standard is already written. A skill, a text for agents or a Knowledge Corpus file have their own rules, kept in documents called rulebooks. The skill consults them instead of inventing the criteria, and cites them instead of copying them.

How to teach it

• The most common mistake is presenting it as «the one that fills in a template». Teach it as the one that sets the objective and the open questions; the template is scaffolding.
• Insist on the gate. A skill refusing to write something comes as a surprise; explain beforehand that an assignment that doesn't push the objective is work that shouldn't exist.
• Explain draft as something healthy. An assignment in draft is not bad: it is honest about what is missing.
• Suggested demo: ask live for an assignment for a real, small job. Let the skill propose the five points and let the group correct them; open the file and point out the header, the questions section and the Progress notes. Then say «advance it» and show the change to ready.
• Check questions: «What does the gate at point 5 do and what are its three outcomes?», «When is a question not an open question?» and «What is the difference between draft and misaligned?».

3.6 question-user

Why it exists

A weak idea can't be committed to, but you don't have to wait for it to mature on its own either. Vagueness is not a reason to postpone: it is exactly this skill's raw material. It serves to turn an idea that is still fuzzy into decisions made.

The facts belong to the skill; the decisions are yours. Everything that can be found out —in your files, in the project's memory, with a search— it finds out itself and never asks you. Your time is spent only on what only you can decide.

The what before the how. What the work has to achieve is the fundamental thing; how it is achieved allows many valid forms. A well-solved how on top of a weak what is lost work. That is why it doesn't ask you any execution detail while the objective, the deliverable or the test that it came out right are still open.

The risk is that you end up nodding along to a plan the agent wrote. If you answer «agreed» forty times, the plan is not yours. That is why the skill records who decided each thing, warns you when you've given three acceptances in a row without any nuance, and never answers its own questions.

How to teach it

• The most common mistake is presenting it as «the one that asks a lot of questions». Teach it as the one that separates facts from decisions: it finds out everything findable and only asks you what is yours.
• Explain the tree and the frontier with a whiteboard example: it makes no sense to ask about the format of a report before knowing who receives it.
• Suggested demo: have someone in the group bring a half-thought idea and say «question me». Show the four fields of each question, switch modes midway through the session and finish by reading the record: point out what was left inferred and ask the group whether they really decided it.
• Check questions: «Why doesn't it ask you for a file path?», «What is the difference between a question that opens and one that closes?» and «What does confirmed proposal mean?».

3.7 maxwell

Why it exists

Whoever did the work can't review it. The session that produced a deliverable is already convinced it came out well. That is why the reviewer is always a fresh subagent, different on each round, that is not whoever did the work. Maxwell doesn't classify: it gathers, records and reports; the one who judges is the reviewer.

The objective is audited; the criteria are only evidence. A deliverable can meet all its criteria and still not serve what it was commissioned for. That is why the verdict on the objective governs. And if there is a part of the objective that no criterion checks, the defect is not in the deliverable but in the yardstick used to measure it (Maxwell calls this a yardstick gap).

The one being reviewed doesn't set the rules of their own review. Neither the session that did the work nor the assignment that commissioned it tells Maxwell which words the ruling may use or what the review covers. If whoever did the work could say «review it and close with PASS or NOT PASSED», they would erase two of the reviewer's four possible answers.

Four rulings, not one more. The vocabulary is closed: no other term counts and none is renamed.

Each caveat carries an owner and one of three destinations: it is fixed before freezing the deliverable; it goes to your environment's pending-items log (or to the report, if your environment doesn't keep that log); or it is accepted with the reason written down.

The last word is yours. Maxwell never sends, publishes, spends, deletes or touches permissions or shared files. Even when the ruling is PASS, the final gate is you.

How to teach it

• The most common mistake is thinking Maxwell «fixes» or «improves» the work. Teach it as a doorman: it says whether it passes or not, and why; fixing belongs to whoever did the work.
• Explain why four rulings and not two. CAVEATS and COULD NOT VERIFY exist so that doubt and lack of proof don't get disguised as PASS.
• Insist on the objective over the criteria with an example: a report that meets every checkbox but is useless for the decision it was commissioned for.
• Suggested demo: run a small deliverable with a deliberate error through Maxwell (for example, a figure that doesn't match its source). Show the ruling, open audit_v1.md and point out the verbatim mandate and the finding with its file:line. Fix only that line and run it through again.
• Check questions: «Why can't the reviewer be whoever did the work?», «What is the difference between NOT PASSED and COULD NOT VERIFY?» and «What is a yardstick gap?».

3.8 pay-de-manzana

Why it exists

Your environment already has things of yours, and none of them can be lost. The rule that governs the whole skill is: «nothing of the user's is lost: what fits is kept; what doesn't fit is moved with a backup, a trace and your approval». That is why it never seeds a template again on top of a file that already exists: it works piece by piece on what is there, and what doesn't fit the new form it moves, it doesn't delete.

What is in your folder is recognized by its shape, not by its label. An environment can say in its index that it is a certain version and not be one, or have pieces from two versions mixed together. That is why the skill reports to you the version declared by your _Memory/INDEX.md, but that version decides no step: what decides is the situation of each piece, seen in its headings, columns and clauses. By the same token, the contents of your folder don't decide the mode either: the mode is decided by what you asked for.

One process with two modes. REVIEW is not a separate analysis: it walks the same reconnaissance and builds the same plan as INTEGRATE, and stops before applying. That way, what REVIEW reports to you is exactly what INTEGRATE would do.

Whoever looks at the disk is not the one who fixes it. The reconnaissance of your folder is always done by a fresh read-only subagent, never the main conversation. That subagent works as a lock: it can't write, so what it reports is what is there, not what the conversation expects to find. If your work surface doesn't allow subagents, the skill stops instead of doing the reconnaissance on its own.

What lives in the app can't be seen from the folder. The instruction boxes, the «Cowork files» setting, the connected folders, the installed skills and the sync live in the app, not on your disk. The skill doesn't take them as good on indirect evidence: it asks you to confirm them, and the boxes are handed to you for you to paste.

A single round of questions and a single yes. Everything it needs to know from you it asks together, at the start, with default values; afterward it presents a complete plan and asks for a single approval, with the right to veto rows. It doesn't interrupt you mid-application.

Running it twice duplicates nothing. Each step checks first whether it is already done, and the plan you approve, with your vetoes, is saved so that the next run doesn't propose again what you already rejected.

Minimal boxes and each piece of data in a single place. The instruction boxes only say where your environment lives, which skill runs on open and on close, and the safety rules for writing; the model's detail lives in INDEX.md and your preferences in profile.md. Each rule lives at a single box level and each piece of data at a single memory level: the lower ones point to the upper ones, they don't copy. If a piece of data lives in two places, sooner or later they contradict each other.

How to teach it

• The most common mistake when teaching it is presenting it as «the installer». Teach it as the one that brings your environment to its current form without losing anything of yours: the backup, the dry-run plan and the single yes are the heart of it, not the folders.
• Teach the two modes with a single idea: REVIEW is INTEGRATE without the apply step. If someone is afraid to touch their environment, let them start with «review my environment».
• Anticipate the manual parts. Pasting boxes, changing «Cowork files», disconnecting folders and installing skills are clicks for the assistant. Say so up front, so nobody expects the skill to do them on its own.
• Suggested demo: on an empty sample folder, run «build my environment» with level «Work only», paste the boxes following the close-and-reopen instruction, and finish with exercise 1 of «My first project». Then run «review my environment» so they can see a report with no changes.
• For the profile: stress that leaving empty slots is desirable and that the burden of proposing is on Claude; the assistant only confirms, corrects or strikes out.
• Check questions: «What is the difference between INTEGRATE and REVIEW?», «What is the setup?» and «Why can't the “Cowork files” folder be inside the master folder?».

3.9 develop-skills

Why it exists

A skill is code that another agent executes, and it is built like code. Without a fixed cycle, a session writes the skill in one go, puts a number on it, packages it and hands it to you «finished» for you to approve afterward. This skill splits the work into stages that you open: you approve the design, you read the draft, you give the order to freeze, you click install.

It doesn't replace skill-creator; it complements it. skill-creator is the general tool for creating skills; develop-skills is the delta for this environment: what is done differently here. The two are loaded together, and each difference between them is declared in a table (see «Divergences from skill-creator»).

Iterating is not versioning. While you fix a draft there is no version number, no log, and no package. The number appears only once, when you freeze. That way version 1.2.0 of a skill is a concrete thing, and not «the one that was in the folder on Tuesday».

Whoever reviews is not whoever made it. The agent that wrote the skill can't approve it. A fresh reviewer, who changes nothing, audits it against written criteria; without its favorable ruling it isn't packaged. It is a gate, not a suggestion.

The skill travels; the environment doesn't. A skill is installed on the account and runs on any machine and in other people's environments. That is why it can't carry paths from your machine, credentials or names of products that someone else may not have, and it has to say what to do when something from outside is missing.

How to teach it

• Teach it as a cycle of approvals, not as a packager. The value is that nothing moves forward without the person's yes: design, draft, freeze, install.
• The hardest idea: iterating is not versioning. Get the group to tell apart «the folder I'm editing» from «version 1.2.0 that was delivered».
• The fresh reviewer is not a suggestion, it is gate 7: the session that made the skill can't approve it, and a PASS with no report behind it doesn't open.
• Suggested demo: take a small sample skill, make a one-line change, run the gates in draft mode and show how they stop at the first failure and what each code means. Close by showing the shelves table and ask which shelf the skill would go on.
• Check questions: «Which change bumps MINOR and which PATCH?», «Why does a skill name ~~drive and not a product?» and «What does the skill do if an object in the environment is missing?».

3.10 write-for-agents

Why it exists

An instruction is code, not documentation. An agent doesn't read a box or a skill to get informed: it executes it. Every line that only informs —history, explanations, advice for the human— is paid for on every read and competes with the lines that do govern. The skill's rule fits on one line: write the current correct behavior, in the positive, for a model to execute; nothing more.

«It's too long» doesn't win arguments; a number does. That is why each text declares its own line budget and is measured against it. The standard doesn't set one for all, because a four-branch procedure and a page of mechanics are not comparable.

A piece of data in two places ends up lying. When it is fixed above and the copy below still has the error, the copy isn't surplus: it lies. That is why each piece of data lives at a single level and the others point to it.

It serves to close writing arguments. Besides the rules, it brings six design criteria (PHILOSOPHY.md). In a dispute, the criterion decides; if none applies, it is a matter of taste and not of standard.

How to teach it

• Teach it with a test, not with a list: «does it instruct or record?». With that single question the group can review any box.
• The most common mistake is trying to slim down by trimming words. Show that what gets removed is entire lines that record or explain.
• Suggested demo: take a sample instruction box that has a paragraph of history, a «be brief» and an example that repeats the instruction. Review it live with the eleven-step order and hand over the findings sheet with file and line.
• Check questions: «Where is an assignment's budget declared?», «Why doesn't a pointer to another piece force the agent to open it?» and «What is the difference between fail and could not verify?».