finding: no shipped example includes a skill, so SKILL.md is learned from an error

[sagi5060]

Problem

No shipped example includes a skill, so the SKILL.md contract is learned from an error message. A
clean-room reviewer's first failure was:

ConfigError: .../SKILL.md: missing a 'description' in its frontmatter.

The format is documented — concepts/skills.mdx:19-33 has a complete example — but the reviewer was
working from examples/, found no skill there, wrote one from memory of the directory listing in the
README, and failed. examples/ currently ships chat-agent-with-a-tool, workflow-with-an-approval
and ask-agentdeck; the first two have no skills/ directory at all.

Skills are one of the four things Deck.from_project() discovers, and the only one with no runnable
example.

Proposed shape

Add a skill to examples/chat-agent-with-a-tool rather than creating a fourth example — the agent
there already has a reason to consult one, and one directory is cheaper than a new example to keep
green:

examples/chat-agent-with-a-tool/.agentdeck/
├── agents/<bundle>/agent.py
└── skills/<name>/SKILL.md          # frontmatter + prose the agent follows

The SKILL.md should demonstrate the contract the docs describe — name matching the directory,
description as the disclosure text, prose instructions — and the README should show the run where
the skill's guidance visibly changes the answer, so the example proves progressive disclosure rather
than merely parsing.

Out of scope: a skill with scripts/, and anything touching #20 (consuming skills via the SKILL.md
protocol rather than as pre-wrapped tools) — this is one static skill exercising today's behavior.

Notes

• Keep it inside the existing example so make check gains one bundle, not one project.
• finding: getting-started dead-ends — skills, sessions and reference are unreachable from the entry path #239 (getting-started next steps) and finding: errors name the problem but never the doc page that answers it #238 (errors naming their page) are the other two halves of the
  same wayfinding finding; this one closes the "no example to copy" leg.

Done when

• examples/chat-agent-with-a-tool ships one skill under .agentdeck/skills/
• Its README shows the skill's guidance changing the agent's answer
• The example still runs with only OPENAI_API_KEY set
• Deck.from_project() in that example discovers the skill without extra arguments

---

New to AgentDeck?

AgentDeck SDK is a production runtime around agents you already have — it supplies sessions,
streaming, one event log per run, human approval and run control, and leaves execution to the
OpenAI Agents SDK and LangGraph.

pip install agentdeck-sdk

Before working on this issue, run this example as a user would — python run.py in
examples/chat-agent-with-a-tool. Fifteen minutes there makes this issue read very differently.

Setup, the make check gate, the branch model (dev) and the CHANGELOG rule are in
CONTRIBUTING.md. Comment here to claim the issue — nobody
else gets assigned while you are working on it, and questions are welcome in
Discussions.

[sagi5060]

Shipping a different shape than proposed — #252

This issue proposed folding a skill into examples/chat-agent-with-a-tool rather than adding a fourth
example directory, on the grounds that one directory is cheaper to keep green. #252 does the opposite,
deliberately: a new examples/agent-with-a-skill/.

The reason the cheap plan was wrong: a skill bolted onto the order desk would be decoration. The example
has to answer "why reach for a skill instead of a longer instructions string", and it can only answer
that if the skill visibly changes the output. "How to write a handover note" does — the model loads it,
then asks for the part the user left out instead of inventing it. Order-status lookup has no equivalent.

The example is a port of the project the reviewer in this issue's report actually built, so the shape is
the one an outsider reached for unprompted: two tools, one skill, two turns on one session. Verified
against a live model — load_skill('shift-notes') fires before file_handover_note.

Cost, stated plainly: one more example for make check to build, and one more README to keep from
rotting. tests/test_examples.py pins the skill by name, so a renamed directory or drifted frontmatter
name fails the gate rather than a model call.