Local Skills

A local Goldiblocks skill is a standalone filesystem package for one or more bundled document folders. The top-level SKILL.md is a thin agent entrypoint: it discovers or creates a selected document folder, then routes the agent to that folder's local instructions.

A shipped local skill must run from its bundled files without fetching this docs site. The repo docs explain the architecture and authority model; the package itself carries the executable instructions, DSL snapshot, input files, and output folder.

Canonical Template

The canonical source for reusable local-skill files is /skill-template/.

Use the template for verbatim file content:

• skill-template/README.md defines what is canonical, what is per skill, placeholder substitution, and propagation rules.
• skill-template/SKILL.md is the canonical package-level agent entrypoint.
• skill-template/documents/{document_handle}/README.md is the canonical selected-document entrypoint.
• skill-template/documents/{document_handle}/document_guide/session_guide.md owns local interview, edit, status, render, and diagnostics procedure.
• skill-template/documents/{document_handle}/document_guide/dsl_spec.md is the bundled runtime DSL snapshot.

When any document-agnostic template file changes, propagate the change to each active skill package. Do not copy template-owned instructions into this page as a second source of truth.

Skill Architecture

Only one local skill mode is needed.

Rules:

• Each local skill package has one top-level SKILL.md.
• SKILL.md stays document-agnostic; only its name, description, and H1 vary per skill.
• SKILL.md lists or discovers child document folders, owns package-level working-copy creation, and then routes the agent to the selected document folder's README.md.
• The selected document folder's README.md owns the document-level read list.
• The selected document folder's document_guide/session_guide.md owns local procedure.
• The selected document folder's document_guide/dsl_spec.md owns the local DSL snapshot only.
• Reusable source documents and active working documents use the same folder shape. Reuse status is metadata, not a separate skill type.

Filesystem Layout

Local MVP uses one skill package with a top-level SKILL.md and one or more self-contained document folders under documents/. The duplicated unit is the child document folder, not the whole skill package.

skills/
  will_skill/
    SKILL.md
    documents/
      simple_will/
        README.md
        document_guide/
          session_guide.md
          dsl_spec.md
        document_input/
          document.md          # the whole document: modules as a sequence
        document_output/

Path conventions:

• Skill package root: skills/{skill_handle}/
• Skill entrypoint: skills/{skill_handle}/SKILL.md
• Document root: skills/{skill_handle}/documents/{document_handle}/
• Document input folder: {document_root}/document_input/
• Document file: {document_root}/document_input/document.md
• Document guide folder: {document_root}/document_guide/
• Markdown output folder: {document_root}/document_output/

A document folder name is the document handle. Do not duplicate the handle in document_input/document.md. Human-friendly names live in document and module bodies, not in folder or file names.

One File Per Document

All of a document's modules live in document.md, as a YAML sequence. There is no modules/ folder and no file-per-module. Sequence position is the order — see Ordering Is Sequence Position.

The earlier layout gave each module its own file so that a module could be referenced directly by filename, in the Obsidian [[wikilink]] model. That model was retired: references bind to stable IDs with the handle demoted to a display hint, because renaming one thing broke every reference to it (see References bind to stable IDs). A module addressed by key is equally addressable wherever it sits, so the file split was buying addressability that filenames no longer provide.

Two consequences worth knowing:

• Grep still works, and reads better. One match shows the module and its neighbours in context. Greppability was explicitly preserved by the stable-ID decision; only filename linking went away.
• The file gets large. A simple will runs to roughly 1,500 lines and a commercial agreement will be several times that. Edit it with targeted string replacement rather than rewriting the whole file, and expect concurrent edits to different modules to share one merge surface.

MVP output is Markdown only. .docx and .pdf conversion are post-MVP concerns.

Clean Sources and Working Copies

The local skill uses one folder shape for all local documents. A folder's role is determined by document_input/document.md frontmatter:

Do not write interview answers into a clean library source folder. To start client or matter work from a source, duplicate the source document folder into a new sibling folder under the same documents/ directory and set the new folder's reuse_type: working. The canonical copy workflow lives in skill-template/SKILL.md.

This is a local convention, not a shared column. The hosted app retired its reuseType column: library standing there is a pin naming an exact sealed edition, not a flag on the folio — see Status Axes → Retired reuseType. What the two sides do share is the discipline: a working copy is a copy, and the clean source is never written into.

Local Spec Snapshots

Each document folder carries a document_guide/dsl_spec.md snapshot so it can run without the docs site. The snapshot is copied from DSL Agent Spec at the pinned syntax_version and snapshot_date.

Authority order for DSL changes:

1. Update DSL Agent Spec.
2. Update the snapshot in skill-template/documents/{document_handle}/document_guide/dsl_spec.md.
3. Propagate the updated snapshot to active skills that exercise the changed feature.

The snapshot's reference metadata is provenance only. Runtime operation must use the bundled snapshot, not fetch the canonical docs page.

File Roles

This page describes file roles only. Use /skill-template/ for canonical file content.

Current state is read from document_input/document.md: module values, module status, module edited_at, and optional status_reason. Document recency is derived from the maximum module edited_at rather than a separate document-level edited_at.

document_input/document.md uses the shared authoring model from Documents, Modules, and Blocks, with local frontmatter for filesystem workflow state. Standard types are defined in DSL Agent Spec → Standard Types.

Agent Rules

These reinforce the canonical authoring rules in the local-execution context:

• Do not treat blocks as interview prompts. Interview guidance lives on module.guide and field-level guide entries under data; blocks are rendered output.
• Treat the active surface (Form / Document) as runtime UI state, not as a stored behavior flag. The legacy uiMode column persists on documentVersions pending migration, but nothing new should read or write it.
• Render only applicable modules and blocks.
• Do not render fill-mode summary blocks into final legal output unless the selected generation mode explicitly includes them.