Cratis documentation authoring
Draft one accurate Cratis documentation page in the voice and structure required
by its document type. This skill owns content. It does not decide which
repository owns a page, wire site navigation, locate an existing source page, or
perform visual QA.
Required inputs
Before drafting, establish:
- the owning repository and destination page;
- document type: tutorial, how-to, explanation, or reference;
- target reader and the outcome they need;
- authoritative product source for every API, command, version, and capability;
- explicit scope and important exclusions.
Use repository evidence to resolve routine details. Ask only when materially
different document types, audiences, or product choices remain plausible.
Route near misses
- New-page placement or navigation is unresolved: defer to
cratis-engineering-docs-add-page.
- The request changes an existing page whose source location is unresolved:
defer to
cratis-engineering-docs-edit-page.
- The request is to render, screenshot, or diagnose visual layout: defer to
cratis-engineering-docs-visual-qa.
- A product/API claim lacks first-party source evidence: stop and identify the
missing authority instead of drafting the claim.
- The subject is not Cratis product or engineering documentation: do not apply
this skill.
Write one document type
Do not mix Diátaxis types on one page:
| Type |
Reader need |
Shape |
| Tutorial |
Learn by completing a guided outcome |
Ordered steps with visible results |
| How-to |
Solve one concrete problem |
Prerequisites, direct procedure, completion check |
| Explanation |
Understand why and when |
Concepts, boundaries, trade-offs, diagram |
| Reference |
Look up exact information |
Exhaustive tables, fields, commands, signatures |
For the detailed mechanical format, read
site-format.md.
Drafting workflow
- Open with the reader's concrete friction and the Cratis capability that
relieves it.
- Organize by the reader's workflow, not by implementation namespaces or an
alphabetical API dump.
- Use active voice, present tense, second person, and American English.
- Explain the invisible behavior after each example: what the framework does
and why the boundary matters.
- Verify every API and command against first-party source at the applicable
revision. Never translate a C# example into another client language by guess.
- State maturity, authorization, side effects, unsupported surfaces, and when a
simpler approach is better.
- Show a visible result in tutorials and procedures. Use Mermaid for a
non-trivial explanation.
- End with the natural next page or workflow.
Correctness boundary
Never invent product APIs, customer claims, versions, support commitments,
marketplace availability, or private implementation details. Do not copy a code
sample from memory. If the source cannot prove a claim, omit it or mark the gap
for the owning maintainer.
A successful build proves rendering, not technical correctness. The owning
repository still runs its documentation, snippet, link, and product gates.
Output
Return or write the page content only at the already approved destination. Do
not modify navigation, generated copies, project context, credentials, package
manifests, or unrelated documentation. Report the authoritative source checked
and the verification that still remains.
1---2name: cratis-engineering-docs-authoring3description: Draft accurate Cratis documentation content after the owning repository, page placement, document type, and authoritative product sources are known. Use for tutorials, how-to guides, explanations, and references; defer placement, existing-page discovery, and visual QA to their companion workflows.4license: LICENSE5---67# Cratis documentation authoring89Draft one accurate Cratis documentation page in the voice and structure required10by its document type. This skill owns **content**. It does not decide which11repository owns a page, wire site navigation, locate an existing source page, or12perform visual QA.1314## Required inputs1516Before drafting, establish:1718- the owning repository and destination page;19- document type: tutorial, how-to, explanation, or reference;20- target reader and the outcome they need;21- authoritative product source for every API, command, version, and capability;22- explicit scope and important exclusions.2324Use repository evidence to resolve routine details. Ask only when materially25different document types, audiences, or product choices remain plausible.2627## Route near misses2829- New-page placement or navigation is unresolved: defer to30 `cratis-engineering-docs-add-page`.31- The request changes an existing page whose source location is unresolved:32 defer to `cratis-engineering-docs-edit-page`.33- The request is to render, screenshot, or diagnose visual layout: defer to34 `cratis-engineering-docs-visual-qa`.35- A product/API claim lacks first-party source evidence: stop and identify the36 missing authority instead of drafting the claim.37- The subject is not Cratis product or engineering documentation: do not apply38 this skill.3940## Write one document type4142Do not mix Diátaxis types on one page:4344| Type | Reader need | Shape |45| --- | --- | --- |46| Tutorial | Learn by completing a guided outcome | Ordered steps with visible results |47| How-to | Solve one concrete problem | Prerequisites, direct procedure, completion check |48| Explanation | Understand why and when | Concepts, boundaries, trade-offs, diagram |49| Reference | Look up exact information | Exhaustive tables, fields, commands, signatures |5051For the detailed mechanical format, read52[site-format.md](references/site-format.md).5354## Drafting workflow55561. Open with the reader's concrete friction and the Cratis capability that57 relieves it.582. Organize by the reader's workflow, not by implementation namespaces or an59 alphabetical API dump.603. Use active voice, present tense, second person, and American English.614. Explain the invisible behavior after each example: what the framework does62 and why the boundary matters.635. Verify every API and command against first-party source at the applicable64 revision. Never translate a C# example into another client language by guess.656. State maturity, authorization, side effects, unsupported surfaces, and when a66 simpler approach is better.677. Show a visible result in tutorials and procedures. Use Mermaid for a68 non-trivial explanation.698. End with the natural next page or workflow.7071## Correctness boundary7273Never invent product APIs, customer claims, versions, support commitments,74marketplace availability, or private implementation details. Do not copy a code75sample from memory. If the source cannot prove a claim, omit it or mark the gap76for the owning maintainer.7778A successful build proves rendering, not technical correctness. The owning79repository still runs its documentation, snippet, link, and product gates.8081## Output8283Return or write the page content only at the already approved destination. Do84not modify navigation, generated copies, project context, credentials, package85manifests, or unrelated documentation. Report the authoritative source checked86and the verification that still remains.
Cratis