Start here

Teaching the agent your domain

Your first real run will be wrong in a specific, boring way. It will quote the wrong price, chase too early, use a tone you would never use, or invent a policy you do not have. The model is not the problem — it has never seen your business.

The instinct is to go and edit the prompt. Resist it. Mycel splits what the agent knows into three layers with different lifetimes, and picking the right one is most of the skill.

Three layers, three lifetimes

Layer	Answers	Changes	Lives in
Skills	How the job is done — procedure, judgment, refusals	Deliberately, reviewed	`wedges/<slug>/skills/*.md`, in git
Knowledge	What is true — prices, policies, quirks, examples	Weekly, sometimes daily	The knowledge API — no redeploy
Corrections	What you actually meant, this time	Every approval	Captured automatically, becomes knowledge

The test is simple. If the answer changes when your prices change, it is knowledge. If it changes when you change your mind about how the work is done, it is a skill. If you are fixing one output rather than a rule, do not touch either — edit the draft at the approval gate and let it be captured.

The smallest useful thing: one fact

Knowledge is markdown, posted at runtime. No deploy, no restart, effective on the next task.

curl -sX POST http://localhost:4000/v1/wedges/invoice-chaser/knowledge \
  -H "authorization: Bearer $MYCEL_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "escalation.md",
    "kind": "document",
    "content": "# Escalation\n\nNever threaten legal action. After the third reminder, hand the account to a human and stop."
  }'

At run time the harness writes every knowledge item into the sandbox under knowledge/. Live items override files with the same name that shipped in the wedge folder, which is what makes an on-disk seed safely editable in production without a release.

Read what a wedge currently knows with GET /v1/wedges/:wedge/knowledge, and edit or remove individual items with PUT / DELETE /v1/knowledge/:id.

Let the agent tell you what it is missing

Guessing what to write down is slow. The better loop is to let the work surface the gaps.

When the agent hits something it cannot answer from its grounding, it records a gap. That appears twice: as a progress event on the task timeline reading Missing knowledge: …, and in a queue you can work through:

GET  /v1/wedges/:wedge/intake                   # the queue + a coverage percentage
POST /v1/wedges/:wedge/intake/:question         # { "answer": "…" }
POST /v1/wedges/:wedge/intake/:question/dismiss # not relevant to my business

The queue merges two sources: questions the wedge author declared up front in wedge.json under intake, and questions the agent discovered while working. Unanswered questions come first, then the ones the agent has hit most often, then the author's own weighting. Evidence outranks opinion.

Answering writes a knowledge item at intake/<question-id>.md containing the question and your words, verbatim. Nothing paraphrases you through a model on the way in. Re-answering updates the same item rather than piling up duplicates.

Of the shipped wedges, books-keeper and geo-monitor declare five intake questions each; every other one — invoice-chaser, gtm-operator, product-builder among them — declares none, so their coverage reads 100% until the agent discovers something.

The loop that costs you nothing: edit before approving

This is the highest-value habit in the whole system. When an approval comes up and the draft is nearly right, do not reject it and go rewrite a skill. Fix the payload in the approve call:

POST /v1/approvals/<id>/approve
{ "edited": { "body": "Hi Sam — quick nudge on INV-1042, $2,400, due April 1…" } }

The edit is merged over the agent's payload and the merged version is what actually goes out. A correction knowledge item is written recording what was proposed and what you changed it to, and a feedback.recorded event lands on the timeline. The next run has your judgment without you having authored anything.

You can also correct after the fact: POST /v1/tasks/:id/feedback with { rating, correction, note }.

Where this does not apply. The correction capture runs on the action proxy path — the gate used by connections. The sandbox plugin gate, which catches tool calls by name pattern, currently discards edited: the decision is honoured but the edit is not applied and no correction is stored. If your gated step is a raw tool call rather than a connection action, treat approve-with-edit as approve.

When to write a skill instead

Corrections and facts do not fix a wrong procedure. Write a skill when the failure is structural: the agent is doing the steps in the wrong order, or it needs a hard refusal. Skills are markdown, one file per procedure, and they are code — versioned, reviewed, deployed.

The most valuable lines in a skill are the negative ones. From the shipped wedges: never invent fees, do not send anything — produce a draft for human approval. Those sentences are why one horizontal engine can run a vertical service without drifting generic.

If you would rather not write it cold, run the mycel-wedge-builder skill in Claude Code — it interviews you and writes wedge.json, the skills and the seed knowledge in your own words.

Failure modes

A knowledge file listed in the manifest silently does not load. Names in knowledge are used verbatim — unlike skills, no .md is appended. "close-policy" loads nothing; "close-policy.md" works. Omit the field entirely to load every file in the folder.
Your edit had no effect next run. Check you edited live knowledge and not the on-disk seed — live wins, so a stale live item silently shadows the file you just fixed.
Coverage says 100% but the agent is still guessing. Coverage counts declared and discovered questions, not correctness. It is a to-do list, not a score.
Knowledge grew and quality dropped. Everything is written into the sandbox for every run. Prune contradictions; two documents disagreeing is worse than neither.

What to read next

Wedges — the manifest that all of this hangs off, and how to make one for your own service.