Skills: From One-Off to Shared Capability

Part 6 of 9 — how recurring procedures get captured, reused, and shared across a whole team.

The third artifact

So far the operator has two kinds of knowledge: tools (what it can do) and soul.md (who it is and what it may decide). A skill is the third: a written procedure for a recurring, multi-step job — the institutional memory of "how we handle this kind of thing here."

A tool is a single lever. A skill is a play: the sequence of levers to pull for a known situation, plus the judgment calls along the way. "Handle a not-as-described claim" isn't one tool; it's read the order, read the messages, check the photos, decide, draft a reply, maybe refund, maybe escalate. That choreography is worth writing down once.

What a skill looks like

A skill is just a Markdown file in skills/ that the agent reads when the situation arises. Here is a complete one:

# skill: handle-not-as-described

Use this when a buyer claims an item is "not as described",
defective, or significantly different from the listing.

## Goal
Resolve fairly and quickly, protect the store's rating, and stay
inside the authority defined in soul.md.

## Steps
1. Pull the full picture:
   - `ebay-get-order --id  --json`
   - `ebay-list-messages --order  --json`
   - Note the item price, what the buyer says is wrong, and any
     photos they attached.
2. Sanity-check the claim against the listing. Is it plausible?
   Is the buyer reasonable, or is this a pattern (repeat claimant)?
3. Decide the path:
   - **Clear, minor, ≤ $100, buyer reasonable** → you may resolve:
     offer a partial or full refund per fairness, draft a warm
     reply, refund with `ebay-refund --reason not-as-described`
     (use `--dry-run` first, show me, then send).
   - **Over $100, ambiguous, or buyer is hostile** → STOP.
     Escalate to the owner per soul.md with a one-line
     recommendation. Do not refund.
4. Always reply to the buyer the same day, even if only to say
   we're looking into it. Never leave a not-as-described claim
   silent — that's what triggers a formal case.
5. Log the outcome in your closing summary.

## Tools used
ebay-get-order · ebay-list-messages · ebay-refund · ebay-reply-message

## Don't
- Don't ask the buyer to ship the item back for a sub-$30 dispute;
  the return shipping costs more than the refund.
- Don't admit fault in writing beyond "we're sorry this happened" —
  acknowledge the experience, fix it, move on.

Notice what the skill does and doesn't do. It encodes the procedure and the local wisdom ("don't ask for a return on a sub-$30 dispute") — the things a seasoned employee knows that aren't in any API. It defers hard authority to soul.md rather than restating limits, so there is one source of truth for "how much can I refund."

Skills vs. tools vs. soul.md

	Tool	Skill	soul.md
Form	Executable program	Markdown procedure	Markdown instructions
Answers	"How do I do X?"	"How do we handle situation Y?"	"Who am I and what may I decide?"
Determinism	Fully deterministic	Followed by the agent (soft)	Followed by the agent (soft)
Changes when	The API changes	The procedure improves	The role or policy changes
Granularity	One action	One recurring job	One operator

How skills accumulate

This is where the pattern earns its keep over time. Skills are not designed up front — they accrete from real work:

A new situation comes up. You and the agent work through it together, ad hoc.
It worked. You say: "Save how we just handled that as a skill." The agent writes the procedure into skills/.
Next time the situation arises, the agent already knows the play. It gets a little better each time you refine it.

The operator literally learns on the job — not by retraining a model, but by writing down what worked in plain language. The "learning" is legible, reviewable, and editable by a human. That is a feature, not a limitation.

Sharing skills across a team

Because tools, soul.md, and skills all live in one git repository (Part 4), sharing is just version control. Concretely:

The repo is the unit of distribution. A teammate clones it, runs the install, and does their own auth login with their account (Part 3). They inherit every tool and skill instantly — but never a credential.
Skills are reviewed like code. A new or improved skill arrives as a pull request. The team can see exactly what behavior is being added before it ships. "How we handle X" becomes a reviewed, agreed artifact rather than tribal knowledge in one person's head.
soul.md can be layered. Keep a shared team soul.md for common voice and rules, and let each operator add a small personal overlay (their store name, their thresholds). Shared spine, personal tuning.
A skill registry can grow. At scale, a team or company maintains a curated library — vetted skills others can pull in, with provenance and an owner. The operator's capabilities become a shared, governed asset that improves for everyone at once.

The compounding effect. The first person to handle a tricky return spends an hour. They save it as a skill. Everyone else — and every future session — handles it in a minute, correctly, in the house voice. Multiply across dozens of situations and the operator becomes the distilled operational know-how of the whole team, kept in files anyone can read.

Build note. Some agents have a native notion of "skills" or "commands" with their own discovery rules; others simply read whatever Markdown you point them at. Keep your skills as plain, portable Markdown in skills/ and reference them from soul.md. If a particular agent has a richer skills mechanism, you can map onto it later without rewriting the content.

We now have every piece. Part 7 puts them together into a working day for the eBay operator.