From open-agreements
Converts plain markdown contract drafts to OpenAgreements' canonical template.md format with YAML frontmatter, cover-term tables, oa:clause directives, [[Defined Term]] paragraphs, and oa:signer blocks that compile to JSON specs and DOCX.
npx claudepluginhub open-agreements/open-agreementsThis skill uses the workspace's default tool permissions.
Convert plain markdown contract drafts into OpenAgreements' canonical `template.md`
Fills standard legal templates (NDAs, SAFEs, cloud service agreements) to produce signable DOCX files. Supports Common Paper, Bonterms, YC templates; sends for DocuSign e-signature.
Generates customized business agreements for 10 types (freelancer, partnership, NDA, etc.) with plain English annotations via info-gathering wizard. Trigger: /agreement-generator or 'create a freelancer agreement'.
Generates service agreement, NDA, and subcontractor templates with scope, payment, IP ownership, confidentiality, termination, and liability clauses. Activates on 'contract' or 'agreement' mentions.
Share bugs, ideas, or general feedback.
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.
Use this skill when the user wants to:
template.mdnpm run generate:templatesoa:clause directives, or signer metadataThis skill assumes:
content/templates/<template-id>/template.md.scripts/template_renderer/canonical-source.mjs)
and the cover-standard-signature-v1 layout are present.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.## Standard Terms — clauses, each preceded by <!-- oa:clause id=... -->.
The first clause should be Defined Terms with type=definitions.## Signatures — <!-- oa:signature-mode arrangement=... --> followed by
exactly two <!-- oa:signer ... --> blocks.---
template_id: openagreements-<slug> # kebab-case, must match the directory slug
layout_id: cover-standard-signature-v1
style_id: openagreements-default-v1
outputs:
docx: content/templates/openagreements-<slug>/template.docx
document:
title: <Document title> # MUST match the H1 below
label: <Catalog label, 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: Cover Terms
heading_title: Cover Terms
standard_terms:
section_label: Standard Terms
heading_title: Standard Terms
signature:
section_label: Signature Page
heading_title: Signatures
---
Notes:
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).output_markdown_path or outputs.markdown — the canonical
compiler rejects them. The canonical template.md is the source.# <Document title>
Keep the H1 text identical to document.title. There is no automatic
cross-validation today, but drift between the two is a known footgun.
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:
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.{snake_case} field placeholder. Field
names must match ^[a-z_][a-z0-9_]*$.always — always rendered.<field_name> — rendered only when the boolean field is truthy. The
field's name must satisfy ^[a-z_][a-z0-9_]*$.Every clause gets a directive, then a ### Heading, then prose paragraphs:
## 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.
Directive attributes:
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.If a clause transfers inventions, work product, patent rights, copyrights, or
other IP ownership, use a present-tense operative grant such as hereby assigns.
Employee hereby assigns to Company all right, title, and interest in ...... and will sign additional documents reasonably requested to confirm ownership.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.hereby irrevocably assigns) is optional belt-and-
suspenders; "hereby assigns" is the doctrinal minimum.Use a Defined Terms clause as the first clause under ## Standard Terms
when a capitalized concept needs an explicit anchor or when a longer definition
materially shortens later operative clauses.
Before adding a definition, ask:
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:
[[...]] span — that span declares the canonical term.A, An, The) before the first [[...]] is allowed
and is stripped from the canonical term.(Aliases: [[Alias 1]], [[Alias 2]]). Aliases never render in the legal
output.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.
## 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):
signature, print-name, title, date) in the same
order. The renderer unions row IDs in declaration order.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.npm run generate:templates
The canonical compiler:
template.md → normalized model.content/templates/<slug>/.template.generated.json.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.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.
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.
| 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). |
---
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 |
## 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.
## 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: _______________
template.md form
and be picked up automatically by npm run generate:templates.For setup of the OpenAgreements repo / CLI, see CONNECTORS.md.