Convert plain markdown contract drafts into OpenAgreements' canonical template.md authoring format — YAML frontmatter, Kind|Label|Value|Show When cover-term tables, oa:clause directives, [[Defined Term]] paragraphs, and oa:signer directives that compile to validated JSON specs and DOCX artifacts. Use when the user says "convert this to canonical markdown," "author a new OpenAgreements template," "migrate template to template.md," or "write a canonical-form contract."
Convert plain markdown contract drafts into OpenAgreements' canonical template.md authoring format — YAML frontmatter, Kind|Label|Value|Show When cover-term tables, oa:clause directives, [[Defined Term]] paragraphs, and oa:signer directives that compile to validated JSON specs and DOCX artifacts. Use when the user says "convert this to canonical markdown," "author a new OpenAgreements template," "migrate template to template.md," or "write a canonical-form contract."
Convert plain markdown contract drafts into OpenAgreements' canonical template.md
authoring format. The canonical form is a single lawyer-editable file that compiles
to a validated JSON contract spec plus a rendered DOCX via the shared template
renderer.
Activation
Use this skill when the user wants to:
Convert a plain-prose contract draft into a canonical OpenAgreements template.md
Migrate an existing JSON-source template to canonical authoring
Author a new template that compiles via npm run generate:templates
Add or refactor a Defined Terms clause, oa:clause directives, or signer metadata
Bring a template into parity with the Wyoming / Employee IP canonical patterns
This skill assumes:
You are working inside an OpenAgreements repo checkout. Templates live at
content/templates/<template-id>/template.md.
The shared canonical compiler (scripts/template_renderer/canonical-source.mjs)
and the cover-standard-signature-v1 layout are present.
Canonical structure overview
A canonical template.md has these parts in this order:
# Title — H1 matching document.title in frontmatter.
## Cover Terms — short subtitle paragraph followed by a
Kind | Label | Value | Show When table with {snake_case} field
placeholders.
Optional recitals section — <!-- oa:section type=recitals -->
followed by an H2 such as ## Recitals and one or more recital paragraphs.
Operative section — <!-- oa:section type=standard_terms --> followed
by an author-chosen H2 such as ## Standard Terms, ## Resolutions, or
## Terms. Clauses live here, each preceded by <!-- oa:clause id=... -->.
The first clause should be Defined Terms with type=definitions when a
definitions clause is needed.
Signature section — followed by the
signature H2 and then plus the
signer blocks.
<!-- oa:section type=signature -->
<!-- oa:signature-mode arrangement=... -->
Step-by-step conversion
Step 1 — Skeleton the frontmatter
---template_id:openagreements-<slug># kebab-case, must match the directory sluglayout_id:cover-standard-signature-v1style_id:openagreements-default-v1outputs:docx:content/templates/openagreements-<slug>/template.docxdocument:title:<Documenttitle># MUST match the H1 belowlabel:<Cataloglabel,e.g."OpenAgreements XYZ">
version: "1.0"
license: Free to use under CC BY 4.0
include_cloud_doc_line: true
defined_term_highlight_mode: definition_site_only # see "Highlight modes"
cover_row_height: 700
sections:cover_terms:section_label:CoverTermsheading_title:CoverTermsstandard_terms:section_label:StandardTermsheading_title:StandardTermssignature:section_label:SignaturePageheading_title:Signatures---
Notes:
Canonical sources do not declare source_json. npm run generate:templates
auto-discovers any content/templates/<slug>/template.md whose frontmatter
declares template_id, layout_id, and style_id, then writes the
generated JSON to content/templates/<slug>/.template.generated.json
(a hidden, do-not-edit-by-hand artifact).
Do not add output_markdown_path or outputs.markdown — the canonical
compiler rejects them. The canonical template.mdis the source.
For directive-backed sections, the body H2 that follows oa:section is the
rendered heading source of truth. Keep the frontmatter sections metadata in
place, but treat the body heading as authoritative for the visible section
title.
Step 2 — Title (H1)
# <Documenttitle>
Keep the H1 text identical to document.title. There is no automatic
cross-validation today, but drift between the two is a known footgun.
If the rendered title or section heading differs from the raw markdown, see
"Sharp edges and renderer transforms" below for the body-vs.-frontmatter
source-of-truth map.
Step 3 — Cover Terms section
Open with one short subtitle paragraph, then the Kind | Label | Value | Show When
table:
## Cover Terms
The terms below are incorporated into and form part of this agreement.
| Kind | Label | Value | Show When |
| --- | --- | --- | --- |
| row | Company | {company_name} | always |
| row | Employee | {employee_name} | always |
| row | Effective Date | {effective_date} | always |
| group | Confidentiality | | always |
| subrow | Trade Secrets Duration | {trade_secret_duration} | always |
| subrow | Other Confidential Information Duration | {other_confidentiality_duration} | confidentiality_other_included |
Rules:
Kind is row, group, or subrow.
row — single-line cover term.
group — section header with no value (leave the Value column blank).
subrow — child of the most recent group; rendered indented.
Label is the lawyer-facing label.
Value is either literal text or a {snake_case} field placeholder. Field
names must match ^[a-z_][a-z0-9_]*$.
Show When:
always — always rendered.
<field_name> — rendered only when the boolean field is truthy. The
field's name must satisfy ^[a-z_][a-z0-9_]*$.
Step 4 — Directive-anchored body sections
Every operative section starts with an oa:section directive. The H2 that
follows may be author-chosen. Every clause inside the operative section then
gets an oa:clause directive, a ### Heading, and prose paragraphs:
<!-- oa:section type=standard_terms -->
## Standard Terms
<!-- oa:clause id=assignment-of-inventions -->
### Assignment of Inventions
Employee hereby assigns and agrees to assign to Company all right, title, and
interest in Covered Inventions, to the extent permitted by law.
<!-- oa:clause id=non-competition when=noncompete_included omitted="[Intentionally Omitted.]" -->
### Non-Competition
During the Restricted Period, Employee must not engage in any Competitive Business
within the Restricted Territory.
If the document needs standalone WHEREAS-style recitals, author them in a
separate recitals section before the operative section:
<!-- oa:section type=recitals -->
## Recitals**WHEREAS**, Company is considering a financing transaction.
**WHEREAS**, the board has reviewed the proposed terms.
<!-- oa:section type=standard_terms -->
## Resolutions
id — slug, kebab-case, unique within the document. Used for stable
machine references.
when=<field_name> (optional) — clause is only included when the named
boolean field is truthy.
omitted="<text>" (optional) — text rendered in place of the body when
when evaluates false.
Step 4A — Present-tense IP assignment language
If a clause transfers inventions, work product, patent rights, copyrights, or
other IP ownership, use a present-tense operative grant such as hereby assigns.
Preferred baseline: Employee hereby assigns to Company all right, title, and interest in ...
If future cooperation is also needed, add it after the present assignment:
... and will sign additional documents reasonably requested to confirm ownership.
Do not rely on agrees to assign or will assign without a present-tense
grant. Federal Circuit contract law applied in the Stanford/Roche line of
cases (FilmTec, DDB Techs, Rasmussen Instruments, the Federal Circuit
decision in Stanford v. Roche, 583 F.3d 832) treats future-tense language
as a promise to assign rather than a present transfer of rights — which
diligence reviewers flag as a gap.
This applies to employee invention-assignment agreements, contractor IP
assignment clauses, work-made-for-hire fallback assignments, and standalone
assignment instruments. It does not apply to NDAs or services agreements
without IP transfer.
"Irrevocably" (e.g. hereby irrevocably assigns) is optional belt-and-
suspenders; "hereby assigns" is the doctrinal minimum.
Step 5 — Defined Terms clause (use when it earns its keep)
Use a Defined Terms clause as the first clause in the
oa:section type=standard_terms operative section when a capitalized concept
needs an explicit anchor or when a longer definition materially shortens later
operative clauses.
Before adding a definition, ask:
Does the definition add real substantive content, or materially reduce
repetition by replacing a long phrase in operative clauses?
Is the term used enough in operative clauses that a short capitalized label
improves readability?
If the substance belongs in a Cover Terms value, can that Cover Terms value
remain the single source of truth?
Do not add pointer-only redefinitions for cover-page-only labels such as
Company, Employee, Effective Date, Governing Law, or Venue. Those
add a second lookup site without improving readability.
If a Cover Terms value contains the real substance of a defined concept, keep
all substantive content there. Use the Defined Terms clause only as a short
anchor when repeated capitalized use improves readability. Do not split one
definition across two sites by writing
[[X]] has the meaning given in Cover Terms ... and includes ....
If you remove a formal definition, do not leave behind an unexplained
capitalized pseudo-term. Either use the exact Cover Terms label in prose
(The Prior Inventions and Excluded Inventions identified in Cover Terms)
or rewrite descriptively in lower-case prose.
<!-- oa:clause id=defined-terms type=definitions -->
### Defined Terms
[[Covered Inventions]] means inventions, software, works of authorship,
discoveries, designs, data models, and related intellectual property created
during employment that arise from Company work, use Company resources, or
relate to Company actual or anticipated business.
[[Confidential Information]] means non-public information that Employee
learns, accesses, or develops during employment, including business strategies,
customer and prospect data, trade secrets, technical and product information,
financial information, personnel information, and any additional information
described in Cover Terms under Confidential Information Definition.
Confidential Information does not include information that (a) was publicly
known when Employee learned it, (b) becomes publicly known through no fault
of Employee, (c) was lawfully known to Employee before employment without
confidentiality restriction, or (d) Employee independently develops outside
the scope of employment without using Confidential Information.
Definition rules:
Every paragraph inside the definitions clause must start its definition body
with a [[...]] span — that span declares the canonical term.
A leading article (A, An, The) before the first [[...]] is allowed
and is stripped from the canonical term.
Optional aliases follow the canonical term immediately as
(Aliases: [[Alias 1]], [[Alias 2]]). Aliases never render in the legal
output.
Canonical terms must be unique. Aliases must be unique and may not collide
with any canonical term.
Step 6 — Explicit references
Anywhere outside the definitions clause, [[Term]] is an explicit reference and
must resolve to a canonical term, an alias, or a clause ID via
[[clause:<id>]]. Plain-text mentions are valid — you do not need to wrap
every "Confidential Information" in brackets. Use [[...]] only when you want
explicit linking semantics.
Step 7 — Signatures section
<!-- oa:section type=signature -->
## Signatures
<!-- oa:signature-mode arrangement=entity-plus-individual -->
By signing this agreement, each party acknowledges and agrees to the obligations
above.
<!-- oa:signer id=company kind=entity capacity=through_representative label="Company" -->
**Company**
Signature: _______________
Print Name: {company_name}
Title: _______________
Date: _______________
<!-- oa:signer id=employee kind=individual capacity=personal label="Employee" -->
**Employee**
Signature: _______________
Print Name: {employee_name}
Title: _______________
Date: _______________
Strict rules (the cover-standard-signature-v1 layout enforces these):
Exactly two signers. Schema rejects any other count.
Same row IDs across signers. Both signers should declare the same set
of row IDs (e.g. signature, print-name, title, date) in the same
order. The renderer unions row IDs in declaration order.
Matching labels and hints. When both signers declare the same row ID,
their label and hint must match. Mismatches are rejected with a clear
error.
arrangement is entity-plus-individual or stacked. Defaults to stacked.
kind is entity, individual, or acknowledging-individual.
capacity is through_representative, personal, or acknowledging.
Sharp edges and renderer transforms
A few parts of canonical template.md are structural-only in source or
normalized by the renderer. If the artifact looks different from the raw
markdown, check these first:
Body H1 is anchor-only. Keep the # ... line readable for humans
navigating the raw .md, but the rendered title comes from frontmatter
document.title. If they drift, the artifact follows frontmatter.
The H2 after <!-- oa:section --> becomes the in-document section
heading. Post-#285, that H2 is the visible section title in the body, so
choose names that read well in the output. Example:
<!-- oa:section type=standard_terms --> + ## Resolutions renders
Resolutions as the in-document heading; the same directive +
## Standard Terms renders Standard Terms. Note that on
cover-standard-signature-v1, the running page header is separately
driven by frontmatter sections.<name>.section_label — if you rename the
body H2 but leave section_label alone, the page header will not change.
[Signature Page Follows] is renderer-inserted. Authors do not write
that string in canonical source. The traditional-consent-v1 layout always
inserts [Signature Page Follows] between the operative section and the
signature section, so seeing it in output but not source is expected.
Signer row values in repeat-backed signature sections get $
auto-prefixed. In a repeat-backed signature section, write
{stockholder.name} in canonical source. The parser rewrites it to
{$stockholder.name} in generated artifacts, so do not "fix" the $
you see there. This rewrite is scoped to signer row values; it does not
fire for other loop contexts.
Use this quick source-of-truth map when deciding where authored text will show
up:
Body # <H1> -> anchor-only for raw .md; not rendered in the artifact
Body ## <heading> immediately after <!-- oa:section type=... --> ->
rendered as the in-document section heading
Body ### <clause heading> plus following paragraphs -> rendered
Frontmatter sections.<name>.section_label -> running page header in
cover-standard-signature-v1 (independent of the body H2)
Body recital paragraphs under <!-- oa:section type=recitals --> ->
rendered in the optional recital section (currently only traditional-consent-v1
emits a recital section; cover-standard-signature-v1 ignores it)
Frontmatter document.title -> rendered as the document title
Frontmatter document.opening_recital -> rendered before the operative
section by traditional-consent-v1; not consumed by
cover-standard-signature-v1
Frontmatter document.label and document.version -> rendered in the
layout footer; exact placement varies by layout
Frontmatter document.license -> consumed in the Markdown export, but
both current DOCX layouts hardcode the footer license string as
"Free to use under CC BY 4.0." rather than reading frontmatter. All
first-party templates currently use that license so the output happens
to match, but don't expect a non-CC-BY-4.0 license to flow through to
the DOCX footer today.
Step 8 — Generate and verify
npm run generate:templates
The canonical compiler:
Parses template.md → normalized model.
Validates definitions, references, signers, and field-name shapes.
Writes the regenerated JSON to content/templates/<slug>/.template.generated.json.
Renders the DOCX via the shared layout to outputs.docx.
After generation:
git diff content/templates/<slug>/.template.generated.json — should be empty
if your source matches the previously committed JSON.
npx vitest run integration-tests/canonical-source-sync.test.ts — proves the
canonical → JSON projection is in sync.
npx vitest run integration-tests/canonical-source-authoring.test.ts integration-tests/template-renderer-json-spec.test.ts packages/contract-templates-mcp/tests/tools.test.ts — broader coverage.
Highlight modes
document.defined_term_highlight_mode controls how defined terms are visually
highlighted in the rendered DOCX:
Mode
Behavior
When to use
definition_site_only
Highlights only at the definition paragraph; brackets are stripped from prose.
Default for templates with a Defined Terms clause. Avoids "too much blue" in body text.
all_instances
Highlights every occurrence of any term in style.defined_terms.
Templates without a Defined Terms clause that still want emphasis on a small fixed list (e.g. Company, Employee).
none
No highlighting.
Plain-text outputs.
If you add a Defined Terms clause, switch to definition_site_only. The
template-wide style.defined_terms list still applies as a fallback for
all_instances mode.
Reference templates
Working canonical templates already in the repo:
content/templates/openagreements-restrictive-covenant-wyoming/template.md —
feature-rich: substantive defined terms paired with narrow cover-term anchors
for operative concepts, group/subrow cover terms, and conditional clauses.
content/templates/openagreements-employee-ip-inventions-assignment/template.md —
simpler: 2 substantive defined terms (Covered Inventions, Confidential Information), present-tense IP assignment language, and all-row cover terms.
When migrating a JSON-sourced template, copy the closer of these two as a
shape reference and adapt.
Pitfalls
Pitfall
Symptom
Fix
Edited template.md but forgot to regenerate
canonical-source-sync.test.ts fails
Run npm run generate:templates and commit the regenerated .template.generated.json diff.
H1 doesn't match document.title
Silent drift; renders the frontmatter title
Keep them in sync manually until cross-validation lands.
output_markdown_path left in frontmatter
Compiler throws
Remove outputs.markdown and any top-level output_markdown_path.
source_json left in frontmatter
Quietly ignored today; will become an error
Remove source_json — JSON paths are now derived from the slug.
Same-id signer rows with different labels
Layout throws "mismatched labels" error
Make both signers' row labels identical, or rename one row's ID.
Three signers
cover-standard-signature-v1 rejects at render
Reduce to two signers, or add a new layout that supports N signers.
Field placeholder uses camelCase
Validation rejects
Use snake_case matching ^[a-z_][a-z0-9_]*$.
Definitions paragraph without a [[...]] declaration
Compiler throws
Every paragraph in a definitions clause must declare a canonical term.
Alias collides with a canonical term or another alias
Compiler throws
Choose a unique alias.
Adding [[...]] everywhere in prose
"Too much blue" in DOCX
Reserve [[...]] for definition sites and explicit references; let plain prose stay plain.
Pointer-only redefinition of a cover-page-only term
Second lookup site with no readability gain
Omit the defined-term entry; use the Cover Terms label directly in prose.
One term split across Cover Terms and Defined Terms
Reader must combine two sources for one definition
Put all substantive content in one place — usually a substantive body definition with optional Cover Terms supplementation.
Capitalized pseudo-term with no exact anchor
Reader cannot tell where the term is defined
Keep an exact anchor (identified in Cover Terms) or rewrite in descriptive lower-case prose.
Bare agrees to assign in an IP assignment clause
Diligence flag — not a present transfer of rights
Use hereby assigns and agrees to assign (see Step 4A).
Minimal complete example
---
template_id: openagreements-example-nda
layout_id: cover-standard-signature-v1
style_id: openagreements-default-v1
outputs:
docx: content/templates/openagreements-example-nda/template.docx
document:
title: Example Mutual NDA
label: OpenAgreements Example Mutual NDA
version: "1.0"
license: Free to use under CC BY 4.0
include_cloud_doc_line: true
defined_term_highlight_mode: definition_site_only
cover_row_height: 600
sections:
cover_terms:
section_label: Cover Terms
heading_title: Cover Terms
standard_terms:
section_label: Standard Terms
heading_title: Standard Terms
signature:
section_label: Signature Page
heading_title: Signatures
---
# Example Mutual NDA## Cover Terms
The terms below are incorporated into and form part of this agreement.
| Kind | Label | Value | Show When |
| --- | --- | --- | --- |
| row | Disclosing Party | {disclosing_party_name} | always |
| row | Receiving Party | {receiving_party_name} | always |
| row | Effective Date | {effective_date} | always |
| row | Confidentiality Term | {confidentiality_term} | always |
<!-- oa:section type=standard_terms -->
## Standard Terms
<!-- oa:clause id=defined-terms type=definitions -->
### Defined Terms
[[Confidential Information]] means non-public information disclosed by a party
that is identified as confidential at the time of disclosure or that a
reasonable person would understand to be confidential given the nature of the
information and the circumstances of disclosure.
<!-- oa:clause id=use-restrictions -->
### Use Restrictions
The Receiving Party identified in Cover Terms will use Confidential Information
solely to evaluate the business relationship contemplated between the parties
and will not disclose Confidential Information to third parties without the
Disclosing Party's written consent.
<!-- oa:clause id=term-and-survival -->
### Term and Survival
Each party's confidentiality obligations apply for the Confidentiality Term
listed in Cover Terms, beginning on the Effective Date. Trade-secret
obligations survive indefinitely.
<!-- oa:section type=signature -->
## Signatures
<!-- oa:signature-mode arrangement=stacked -->
By signing this agreement, each party acknowledges and agrees to the obligations above.
<!-- oa:signer id=disclosing kind=entity capacity=through_representative label="Disclosing Party" -->
**Disclosing Party**
Signature: _______________
Print Name: {disclosing_party_name}
Title: _______________
Date: _______________
<!-- oa:signer id=receiving kind=entity capacity=through_representative label="Receiving Party" -->
**Receiving Party**
Signature: _______________
Print Name: {receiving_party_name}
Title: _______________
Date: _______________
Notes
Canonical authoring is the standard authoring format for OpenAgreements
templates. New templates and migrations of existing JSON-source or
Contract-IR-source templates should land in canonical template.md form
and be picked up automatically by npm run generate:templates.
This tool does not provide legal advice — consult an attorney.
Connectors
For setup of the OpenAgreements repo / CLI, see CONNECTORS.md.
