| name | theory-plus-practice-prompts |
| description | Every long-form technical document combining a framework explanation with a use-case demonstration MUST carry executable real-data prompts alongside the conceptual claims. No theory without prompts. No prompts without theory. The medium imitates the substrate. Triggers — authoring a Confluence POC page, an arm-level whitepaper, a client deliverable, a developer-facing onboarding doc, ANY artifact that asks the reader to act on what they read. |
theory-plus-practice-prompts
The canon
Every long-form technical document combining a framework explanation with a use-case demonstration must carry executable real-data prompts alongside the conceptual claims.
No theory without prompts. No prompts without theory. The medium imitates the substrate.
The lesson that provoked this skill
An arm-level POC, 2026-06-05. Operator published a 111-line intro page to the client's Confluence. Single page, conceptual framing, well-written, zero prompts. Sponsor read it. Reaction (paraphrased): the page felt small relative to the weeks of work behind it.
Underdelivery wasn't word count. It was the absence of executable substance. The page explained the framework; it didn't show the framework operating on the client's surface.
Operator pivoted (paraphrased): cite prompt examples — even similar to ones used in real life — so the reader learns to use them. The page should read as a guide, not just theory.
The burst that followed published 10 child pages totaling 2,501 lines / 142 KB — every page combining framework narrative WITH copy-paste-ready prompts hitting @pmdgithub, APR-*, ResolveMSSQLDatabases, real ADH terminology. Plus a dedicated Prompt Cookbook page consolidating 30+ prompts across 6 scenarios.
The skill captures the pattern so this lesson doesn't have to be re-learned on the next arm.
Why this is structurally correct (three reasons)
1. Theory alone = academic. Practice alone = magic. Together = pedagogy.
| Solo theory | Solo prompts | Theory + practice |
|---|
| "MCP is an open standard for AI agents to talk to external systems." | "Paste this into Cursor: '...'" | Reader sees the why (theory) AND the how (prompt) in one session. Learns the pattern by reading + doing in one place. |
| Read once, forgotten. | Looks like a trick — reader executes without understanding, can't generalize, can't argue with the design. | Generates capacity to extend, not just capacity to imitate. |
2. Real-data prompts make the framework non-dismissible
Prompts that use real client terminology (@pmdgithub, APR-*, ResolveMSSQLDatabases) cannot be dismissed with "sure, but our setup is different." The setup IS theirs. The proof is IN the prompt.
This converts the document from:
"X could work for [client]" (hypothesis)
→
"X works AT [client] — here are the queries with their repos, their tickets, their systems" (demonstration)
The difference between selling a hypothesis and demonstrating a result. The second is defensible in a standup the day after publishing. The first reads like marketing.
3. The medium imitates the substrate
A framework whose own brain has 200+ skills (each skill = <description of what it does> + <examples of when to invoke>) cannot publish documentation about itself as theory-only without betraying its own pattern. The format of the docs must mirror the format of the framework. Coherence between message and medium.
For Octorato specifically: the published POC should read as a skill of Octorato being read from the inside, not as a whitepaper about Octorato being read from the outside. The intro establishes; the child pages demonstrate; the cookbook operates.
Mandatory pattern for long-form technical documents
Document-level structure
Every framework-explanation document combines THREE layers:
- Conceptual narrative — what the framework is, why it exists, what assumptions it rests on
- Use-case demonstration — how it applies to the specific client / domain / problem
- Executable prompts — real queries that hit real systems with real terminology
Failure modes:
- Layer 1 only → academic, decays into shelfware in 6 weeks
- Layer 2 only → demo material, fades when the demo is over
- Layer 3 only → looks like cheating, no defensible architecture behind it
- All three → pedagogically complete; survives both the casual reader (skims theory + prompts) and the skeptic (reads everything, finds nothing to dismiss)
Page-level structure
Each substantive page within a multi-page deliverable carries a Try these prompts (or equivalent) section. Minimum 3 prompts. Maximum: as many as illuminate distinct scenarios.
Each prompt has uniform anatomy:
ID — short name (e.g., R1, P4, X2 — keyed to the page's scenario)
Prompt: "<the exact text to paste into Cursor / Claude Desktop / agent>"
Planes: which MCP server(s) / tool(s) it exercises
Tools: which underlying tools the agent will likely invoke
Why it's hard today: 1-2 lines on the manual alternative
Expected shape: what success looks like (sample output structure)
Variations: optional — adjacent prompts for related questions
Uniform structure means the reader learns the shape once and reads every subsequent prompt in seconds.
Suite-level structure (the cookbook)
If the deliverable has more than ~3 substantive pages with prompts each, consolidate into a dedicated cookbook page — one page that organizes all prompts by scenario (Onboarding / Day-to-day / Planning / Archaeology / Compliance / Cross-cutting / etc.). The cookbook is:
- The hands-on entry point for engineers who want to act, not read
- The reference reviewers cite when discussing specific capabilities
- The artifact most likely to be bookmarked and revisited
Anti-patterns (what NOT to do)
| Anti-pattern | Why it fails | What to do instead |
|---|
| "We'll add example prompts later" | Later never comes. The doc decays into shelfware before the prompts are added. | Add prompts in the FIRST published version, even if rough. Better drafts beat empty promises. |
Generic prompts (e.g., "list all repos in the org") | Reader can't tell if the framework knows their specific setup. | Use real client repos / project keys / system names. If you can't, the framework hasn't been studied deeply enough yet. |
| Prompts buried in an appendix | Reader has to leave the page to act. | Embed prompts inline with the theory they exemplify. |
| Prompts without expected-shape annotations | Reader has no way to know if their result is correct. | Always show what success looks like. Empty results are a finding too — document them. |
| Theory page + separate prompt cookbook page with NO cross-references | Theory readers never reach the cookbook; cookbook users never see the theory. | Every theory page links FORWARD to the cookbook entries it exemplifies. Cookbook entries link BACKWARD to the theory pages they implement. |
| Prompts that require the substrate to be perfect | Brittle — one bug breaks the demo. | Include prompts that probe FAILURE modes too. "Try X. Expected result: honest 403 with the gated scope named — not a fabricated response." Honest failure is part of the value. |
| Single mega-prompt that "does everything" | Reader can't disentangle the demonstration. | Smaller, scenario-keyed prompts that each demonstrate ONE primitive of the framework. |
When this skill applies
| Context | Apply? |
|---|
| Client POC / assessment document | Yes — always. This is the canonical case. |
| Internal whitepaper about a framework | Yes. Even internal readers benefit from theory + practice. |
| Onboarding documentation for a new tool | Yes. First-week engineers learn faster by doing than by reading. |
| Compliance / regulatory write-up | Yes — adapt. Prompts in this context demonstrate the audit trail, the routing decisions, the failure modes — not the "happy path" capability. |
| Quick Slack post about a feature | No — too small. Apply only to documents that ask the reader to act on what they read. |
| Marketing copy | No — different audience, different success criteria. |
| API reference for a library | Partially — the API reference IS the practice; examples should be runnable. The "theory" layer is the design rationale section. |
Verification checklist for any document this skill applies to
Before publishing, check:
Companion skills
human-cadence — for the prose between prompts. Prompts are precise by nature; the narrative connecting them should not drift into AI-tells.source-citation-tagging — every claim in the theory layer must carry a source tag so reviewers can challenge specific assertions by source.octorato-harmony — the prompts themselves must use the canonical literal for each name. @pmdgithub everywhere; not @pmdgithub in one place and pmdGitHub in another.no-history-in-docs — changelogs at the bottom of the page. Iteration artifacts ("added in v3") do not appear in the body.harmonization-over-accretion — when adding new prompts in revisions, harmonize with existing ones (same anatomy, same naming scheme). Don't accrete inconsistent formats.
Historical note
This skill was authored on 2026-06-05 from a publication-burst lesson during an arm-level POC. Operator's correction (paraphrased): cite prompt examples similar to ones used in real life so the reader learns to use them — the page should read as a guide, not just theory. That correction is the exact pattern this skill canonizes. The first published deliverable to apply this skill end-to-end was a Confluence tree of 1 parent + 10 children (with a dedicated cookbook child page) authored over a single late-evening session.
Future evolution: if the cookbook page grows beyond ~50 prompts, consider splitting by scenario into separate cookbook pages (Onboarding cookbook / Archaeology cookbook / etc.) rather than letting one page grow unboundedly. The 50-prompt threshold is provisional — revise when first hit.
