@jeremiewerner/motto 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jérémie Werner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/motto.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * motto CLI entry point — thin shell.
+ *
+ * Parses the subcommand with node:util parseArgs (allowPositionals, strict:true
+ * so unknown flags throw and are caught to print usage). Dispatches to the lint
+ * orchestrator or reserves the build slot for Phase 3.
+ *
+ * Output format (D2-11):
+ *   Clean:  "✓ N skills OK" to stdout, exit 0.
+ *   Errors: "✗ <skill>: <message>" per error to stdout, exit 1.
+ *   Usage:  "usage: motto <lint|build>" to stderr, exit 1.
+ *
+ * Exit codes: always set via process.exitCode (never process.exit(1)) to
+ * avoid truncating buffered stdout (Pitfall 7). The only exception is
+ * process.exit() (no arg) in the parseArgs catch block, which is safe because
+ * we have already written all output to stderr before calling it.
+ */
+
+import { parseArgs } from 'node:util';
+import { lintProject } from '../src/lint.js';
+
+// ---------------------------------------------------------------------------
+// Parse argv — strict:true throws on any unknown flag (e.g. --help)
+// ---------------------------------------------------------------------------
+
+let parsed;
+try {
+  parsed = parseArgs({
+    args: process.argv.slice(2),
+    options: {},
+    allowPositionals: true,
+    strict: true,
+  });
+} catch {
+  // Unknown flag (strict:true) — print usage and exit (Pitfall 4, D2-16)
+  process.stderr.write('usage: motto <lint|build>\n');
+  process.exitCode = 1;
+  process.exit(); // exits with exitCode 1; safe: all output written before this call
+}
+
+const sub = parsed.positionals[0];
+
+// ---------------------------------------------------------------------------
+// Subcommand dispatch
+// ---------------------------------------------------------------------------
+
+if (sub === 'lint') {
+  // cwd-only, v1 (D2-15)
+  const result = await lintProject(process.cwd());
+  if (result.ok) {
+    process.stdout.write(`✓ ${result.count} skills OK\n`);
+  } else {
+    for (const e of result.errors) {
+      process.stdout.write(`✗ ${e.skill}: ${e.message}\n`);
+    }
+    process.exitCode = 1; // D2-11; process.exit(1) NOT used (Pitfall 7)
+  }
+} else if (sub === 'build') {
+  // cwd-only, mirrors lint branch (D3-15)
+  const { buildProject } = await import('../src/build.js');
+  const result = await buildProject(process.cwd());
+  if (result.ok) {
+    // D3-16: output dir + one-line summary
+    process.stdout.write(
+      `✓ built ${result.outDir} — ${result.skillCount} skills, ${result.bucketCount} plugin(s)\n`,
+    );
+  } else {
+    for (const e of result.errors) {
+      process.stdout.write(`✗ ${e.skill}: ${e.message}\n`);
+    }
+    process.exitCode = 1; // never process.exit(1) — preserves stdout flush (Pitfall 7)
+  }
+} else {
+  // Unknown subcommand or no subcommand at all (D2-16)
+  process.stderr.write('usage: motto <lint|build>\n');
+  process.exitCode = 1;
+}

package/dist/public/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "motto",
+  "version": "0.0.3",
+  "description": "Motto is a framework for authoring, validating, and packaging Claude Code Agent Skills into self-contained, distributable plugins."
+}

package/dist/public/author-skill/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: author-skill
+description: Teaches how to write a conforming SKILL.md for the Motto framework. Use this skill when authoring a new Motto skill or investigating a lint error.
+audience: public
+shared_references:
+  - skill-schema
+---
+
+# Authoring a Motto Skill
+
+**Role:** You are a hands-on guide for writing Motto SKILL.md files. Walk the author through each required frontmatter field, the body spine contract, and shared references step by step, citing the exact lint error messages they will see if something is wrong.
+
+A Motto skill is a `SKILL.md` file that Motto validates and packages into a Claude Code Agent Skill plugin. You write the source; Motto handles distribution.
+
+## Required Frontmatter Fields
+
+Every SKILL.md must open with a frontmatter block — a `---`-delimited YAML section — containing three required fields.
+
+### `name`
+
+The skill's identifier. Must be a **letter-start kebab-case** string matching `^[a-z][a-z0-9]*(-[a-z0-9]+)*$` and must equal the skill's folder name exactly. See the bundled `skill-schema` reference for the full regex, reserved-word list, and all four lint error messages in the name validation cascade.
+
+```yaml
+name: my-skill
+```
+
+### `description`
+
+A short, non-empty string stating what the skill does and when an agent should trigger it. Keep it under 1024 characters and avoid XML-like tags (`<`, `>`).
+
+```yaml
+description: Explains how to configure my-skill. Use this skill when setting up a new my-skill configuration.
+```
+
+**Lint error if missing:** `description is required`
+
+### `audience`
+
+Must be exactly `public` or `private`.
+
+- `public` — skill is shipped in the public plugin bucket (`dist/public/`)
+- `private` — skill is shipped in the private plugin bucket (`dist/private/`) only
+
+```yaml
+audience: public
+```
+
+**Lint error if wrong:** `audience must be public|private`
+
+## The Body Spine
+
+After the closing `---` delimiter, the skill body must satisfy two independent checks. If both fail, both errors are reported in a single lint run.
+
+**H1 title:** The first non-blank line must be an H1 heading — `# Title` with at least one non-space character after `# `.
+
+**Role line:** The body must contain at least one line beginning with `**Role:`. Write a complete, behavioral sentence — "You are a..." — not just a label. An empty `**Role:**` passes the validator but produces unusable agent instruction content.
+
+```markdown
+# My Skill Title
+
+**Role:** You are a guide who walks the author through every step of X.
+```
+
+## Optional Frontmatter
+
+### `shared_references`
+
+A YAML array of bare basenames — no `.md` extension, no path separators. Each entry must correspond to an existing `shared/references/<entry>.md` file.
+
+```yaml
+shared_references:
+  - skill-schema
+  - another-reference
+```
+
+`motto build` copies each referenced file into the skill's `references/` directory in the output, making the skill self-contained when distributed. If a skill already has a local `references/<entry>.md`, build will report a collision and stop.
+
+**Lint error if file is missing:** `shared_references entry "X" not found in shared/references/`
+
+### `template` and `dependencies`
+
+Accepted and passed through verbatim; not validated in v0.0.2.
+
+## Annotated Minimal Example
+
+The following is a minimal, correct SKILL.md showing every required field and the mandatory body spine:
+
+```yaml
+---
+name: my-skill
+description: Shows how to configure my-skill. Use this skill when setting up my-skill for the first time.
+audience: public
+---
+
+# My Skill
+
+**Role:** You are a guide who walks the author through configuring my-skill step by step.
+
+Main body content goes here.
+```
+
+The folder containing this file must be named `my-skill` to match the `name` field.
+
+## Common Lint Errors
+
+| Error message | Cause | Fix |
+|---------------|-------|-----|
+| `name is required` | `name` field is missing | Add `name: your-skill-name` |
+| `name must be letter-start kebab-case (...)` | Uppercase, underscores, leading digit, or double hyphen | Use lowercase letters, hyphens only, starting with a letter |
+| `name must not contain the reserved substrings "anthropic" or "claude": "X"` | Skill name contains a reserved substring | Rename the skill folder and `name` field |
+| `name "X" must equal its folder name "Y"` | `name` field does not match the folder name | Rename the folder or fix the `name` field |
+| `description is required` | `description` field is missing or empty | Add a non-empty `description` |
+| `audience must be public\|private` | `audience` is missing or has an unexpected value | Set `audience: public` or `audience: private` |
+| `body must begin with an H1 title line (# Title) as its first non-blank line` | Body does not start with `# Title` | Make the first non-blank line after `---` an H1 |
+| `body must contain a **Role:** line` | No line starting with `**Role:` in the body | Add `**Role:** You are...` to the body |
+| `shared_references entry "X" is an unsafe basename (must not contain "/" or ".")` | Entry contains a path separator or extension | Use a bare basename like `skill-schema`, not `./skill-schema.md` |
+| `shared_references entry "X" not found in shared/references/` | Declared shared ref file does not exist | Create `shared/references/X.md` or fix the basename |

package/dist/public/author-skill/references/skill-schema.md

@@ -0,0 +1,163 @@
+# Motto Skill Schema Reference
+
+This file is the canonical rule source for the Motto skill schema (v0.0.2).
+It is bundled verbatim by `motto build` into each public skill's `references/` directory.
+All claims are derived from `src/schema.js`, `src/config.js`, `src/frontmatter.js`, and `src/lint.js`.
+
+---
+
+## 1. `name` Field
+
+**Rule:** A skill's `name` must be a letter-start kebab-case identifier.
+
+Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
+- Starts with exactly one lowercase letter (not a digit, not a hyphen)
+- Followed by zero or more lowercase letters or digits
+- Then zero or more groups of (one hyphen + one or more lowercase letters/digits)
+
+**Additional constraints:**
+- Must equal the skill's folder name exactly. If the folder is `my-skill`, the `name` field must be `my-skill`.
+- Max 64 characters (Claude Code platform limit; enforced by the Motto validator as a cascade step).
+- Must not contain the substrings `anthropic` or `claude` (substring match, not word boundary).
+
+**Name validation cascades — it stops at the first failure:**
+
+| Step | Check | Lint error emitted |
+|------|-------|--------------------|
+| 1 | `name` is missing, empty, or falsy (also covers non-string falsy values) | `name is required` |
+| 2 | `name` is a truthy non-string (boolean, number, array, object) | `name must be a string (got <typeof>)` |
+| 3 | `name` fails the kebab regex | `name must be letter-start kebab-case (/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/): "X"` |
+| 4 | `name` exceeds 64 characters | `name must not exceed 64 characters (got N): "X"` |
+| 5 | `name` contains a reserved substring | `name must not contain the reserved substrings "anthropic" or "claude": "X"` |
+| 6 | `name` does not match the folder | `name "X" must equal its folder name "Y"` |
+
+Valid examples: `my-skill`, `abc`, `a1`, `abc-def-123`
+Invalid examples: `0bad` (leading digit), `My_Skill` (uppercase/underscore), `my--skill` (double dash), `-bad` (leading dash)
+
+---
+
+## 2. `description` Field
+
+**Rule:** Must be present and non-empty.
+
+```
+description: A concise description of what this skill does and when to use it.
+```
+
+**Authoring guidance:**
+- State both what the skill does AND when an agent should trigger it.
+- Max 1024 characters (enforced by the Motto validator).
+- Must not contain XML-tag shapes (e.g. `<example>`, `</p>`, `<br/>`). Plain comparison/math
+  text such as `a<b` is not flagged; only strings matching the tag-shape regex are rejected.
+
+**Lint errors:**
+- `description is required`
+- `description must not exceed 1024 characters (got N)`
+- `description must not contain XML tags (e.g. <example>)`
+
+---
+
+## 3. `audience` Field
+
+**Rule:** Must be exactly the string `public` or `private`. Any other value (including missing) is an error.
+
+```yaml
+audience: public   # shipped in dist/public/ bucket
+audience: private  # shipped in dist/private/ bucket only
+```
+
+**Lint error if wrong:** `audience must be public|private`
+
+**Build behavior:**
+- `public` skills are copied to `dist/public/<skill-name>/`
+- `private` skills are copied to `dist/private/<skill-name>/`
+- `plugins.private` must be set in `motto.yaml` before any private skill can be built
+
+---
+
+## 4. Body Spine — Two Independent Checks
+
+The skill body (the Markdown after the closing `---` delimiter) must satisfy two checks. Both run independently — both errors are reported even if both fail at once.
+
+**Check 1 — H1 title:** The first non-blank line of the body must match `^# \S` (an H1 heading with at least one non-space character after `# `).
+
+```markdown
+# My Skill Title
+```
+
+**Lint error if missing:** `body must begin with an H1 title line (# Title) as its first non-blank line`
+
+**Check 2 — Role line:** The body must contain at least one line that starts with `**Role:` (multiline match).
+
+```markdown
+**Role:** You are a hands-on guide who walks the author through...
+```
+
+The Role line content after `:` is not validated. An empty `**Role:**` passes the regex but produces unusable agent instruction content. Write Role lines as complete, behavioral sentences.
+
+**Lint error if missing:** `body must contain a **Role:** line`
+
+---
+
+## 5. `shared_references` Field
+
+**Rule:** Optional. When present, must be a YAML array of strings. Each entry must be a safe basename.
+
+```yaml
+shared_references:
+  - skill-schema
+  - another-reference
+```
+
+**Per-entry rules:**
+- Must NOT contain `/` or `.` — bare basenames only, no path separators or extensions
+- Must correspond to an existing `shared/references/<entry>.md` file
+
+**Per-entry lint errors:**
+- `shared_references entry "X" is an unsafe basename (must not contain "/" or ".")`
+- `shared_references entry "X" not found in shared/references/`
+
+**Build behavior:** `motto build` copies `shared/references/<entry>.md` into each skill's `dist/<audience>/<skill-name>/references/` directory, making the skill self-contained.
+
+**Collision guard:** If a skill already has a local `references/<entry>.md`, build will report a collision and stop.
+
+---
+
+## 6. `template` and `dependencies` Fields
+
+These fields are accepted and passed through verbatim. They are NOT validated in Motto v0.0.2.
+
+```yaml
+template: some-template
+dependencies:
+  - another-skill
+```
+
+---
+
+## 7. Frontmatter Envelope
+
+Every SKILL.md must open with a bare `---` on line 1 and close with a matching bare `---`.
+
+```
+---
+name: my-skill
+description: What this skill does and when to use it.
+audience: public
+---
+
+# My Skill Title
+
+**Role:** You are...
+```
+
+**Rules:**
+- The opening `---` must be the very first line (no blank lines, no BOM — BOM is stripped automatically).
+- A matching closing `---` is required.
+- YAML between the delimiters is parsed with the `yaml` v2 library (YAML 1.2 core schema) — `yes`/`no`/`on`/`off` are NOT treated as booleans.
+- A stray `---` inside the body is flagged only if the content between it and the body start parses as a clean, non-empty YAML mapping. Wrapping example SKILL.md blocks in fenced code blocks avoids this edge case.
+
+**Lint errors:**
+- `missing frontmatter: file must begin with a '--- ... ---' block`
+- `unterminated frontmatter: no closing '---' delimiter found`
+- `stray '---' delimiter in frontmatter: the block must contain exactly one closing '---'`

package/dist/public/setup-project/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: setup-project
+description: Walks through initializing a Motto project — directory layout, motto.yaml configuration, and running lint and build. Use this skill when starting a new Motto project.
+audience: public
+shared_references:
+  - skill-schema
+---
+
+# Setting Up a Motto Project
+
+**Role:** You are a Motto project setup guide. Walk the author through the source directory layout, every motto.yaml field, the lint and build commands, and what the dist/ output contains.
+
+## Directory Layout
+
+A Motto project uses a fixed directory structure:
+
+```
+my-project/
+  skills/
+    my-skill/
+      SKILL.md              ← one skill per folder
+      references/           ← optional local references (skill-specific)
+    another-skill/
+      SKILL.md
+  shared/
+    references/             ← shared references bundled into multiple skills at build time
+      skill-schema.md
+  motto.yaml                ← project configuration
+  dist/                     ← generated output; never edit manually
+```
+
+Rules:
+- Each skill lives in its own folder under `skills/`. The folder name must match the `name` field in the skill's `SKILL.md`.
+- `shared/references/` holds Markdown reference files that can be declared by multiple skills and bundled by `motto build`.
+- `dist/` is created (and wiped) by `motto build`. Do not commit it.
+
+## `motto.yaml` Fields
+
+The root `motto.yaml` configures the project and both plugin buckets.
+
+```yaml
+name: my-project
+version: "0.1.0"
+description: A short description of what this project's skills do.
+plugins:
+  public: my-project-skills
+  private: my-project-private   # only required when private-audience skills exist
+```
+
+| Field | Required | Rule | Example |
+|-------|----------|------|---------|
+| `name` | Yes | Truthy string; used as project identifier | `motto` |
+| `version` | Yes | Truthy string; recommend semver; quote it to ensure a YAML string | `"0.1.0"` |
+| `description` | Yes | Truthy string; feeds into each built plugin.json | `"A framework for..."` |
+| `plugins.public` | Yes | Letter-start kebab-case (`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`); cannot contain `anthropic` or `claude` | `my-project-skills` |
+| `plugins.private` | Only when private skills exist | Same kebab-case rule as `plugins.public` | `my-project-private` |
+
+See the `skill-schema` reference for the full kebab regex and name constraint rules.
+
+## Running Lint
+
+```
+node bin/motto.js lint
+```
+
+or, once installed globally:
+
+```
+motto lint
+```
+
+**Clean output:**
+
+```
+✓ 3 skills OK
+```
+
+**Error output (example):**
+
+```
+✗ my-skill: name must be letter-start kebab-case ...
+✗ my-skill: body must contain a **Role:** line
+✗ (project): missing plugins.public
+
+3 errors
+```
+
+Lint validates the config (`motto.yaml`), loads shared references, then validates every skill in `skills/`. All errors from all skills are reported in a single run.
+
+## Running Build
+
+```
+node bin/motto.js build
+```
+
+or:
+
+```
+motto build
+```
+
+Build runs lint first. If lint fails, no files are written to `dist/`. On success, `dist/` is wiped and rebuilt.
+
+### What `dist/` Contains
+
+```
+dist/
+  public/
+    .claude-plugin/
+      plugin.json           ← { "name": "my-project-skills", "version": "...", "description": "..." }
+    my-skill/
+      SKILL.md              ← verbatim copy from skills/my-skill/SKILL.md
+      references/
+        skill-schema.md     ← copied from shared/references/ (if declared)
+  private/
+    .claude-plugin/
+      plugin.json           ← { "name": "my-project-private", "version": "...", "description": "..." }
+    secret-skill/
+      SKILL.md
+```
+
+- `plugin.json` is generated from `motto.yaml` fields (`name`, `version`, `description`).
+- Shared references declared in a skill's `shared_references` field are bundled into that skill's `references/` directory.
+- Private skills appear only in `dist/private/`. The public plugin never contains private skill content.
+
+## Installing the Built Plugin in Claude Code
+
+After building, point Claude Code at the output directory for the bucket you want to install:
+
+- **Public plugin:** install from `dist/public/`
+- **Private plugin:** install from `dist/private/`
+
+Use the `claude plugin add` command (or the Claude Code UI) with the path to the bucket directory. Each bucket contains a valid `.claude-plugin/plugin.json` manifest.

package/dist/public/setup-project/references/skill-schema.md

@@ -0,0 +1,163 @@
+# Motto Skill Schema Reference
+
+This file is the canonical rule source for the Motto skill schema (v0.0.2).
+It is bundled verbatim by `motto build` into each public skill's `references/` directory.
+All claims are derived from `src/schema.js`, `src/config.js`, `src/frontmatter.js`, and `src/lint.js`.
+
+---
+
+## 1. `name` Field
+
+**Rule:** A skill's `name` must be a letter-start kebab-case identifier.
+
+Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
+- Starts with exactly one lowercase letter (not a digit, not a hyphen)
+- Followed by zero or more lowercase letters or digits
+- Then zero or more groups of (one hyphen + one or more lowercase letters/digits)
+
+**Additional constraints:**
+- Must equal the skill's folder name exactly. If the folder is `my-skill`, the `name` field must be `my-skill`.
+- Max 64 characters (Claude Code platform limit; enforced by the Motto validator as a cascade step).
+- Must not contain the substrings `anthropic` or `claude` (substring match, not word boundary).
+
+**Name validation cascades — it stops at the first failure:**
+
+| Step | Check | Lint error emitted |
+|------|-------|--------------------|
+| 1 | `name` is missing, empty, or falsy (also covers non-string falsy values) | `name is required` |
+| 2 | `name` is a truthy non-string (boolean, number, array, object) | `name must be a string (got <typeof>)` |
+| 3 | `name` fails the kebab regex | `name must be letter-start kebab-case (/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/): "X"` |
+| 4 | `name` exceeds 64 characters | `name must not exceed 64 characters (got N): "X"` |
+| 5 | `name` contains a reserved substring | `name must not contain the reserved substrings "anthropic" or "claude": "X"` |
+| 6 | `name` does not match the folder | `name "X" must equal its folder name "Y"` |
+
+Valid examples: `my-skill`, `abc`, `a1`, `abc-def-123`
+Invalid examples: `0bad` (leading digit), `My_Skill` (uppercase/underscore), `my--skill` (double dash), `-bad` (leading dash)
+
+---
+
+## 2. `description` Field
+
+**Rule:** Must be present and non-empty.
+
+```
+description: A concise description of what this skill does and when to use it.
+```
+
+**Authoring guidance:**
+- State both what the skill does AND when an agent should trigger it.
+- Max 1024 characters (enforced by the Motto validator).
+- Must not contain XML-tag shapes (e.g. `<example>`, `</p>`, `<br/>`). Plain comparison/math
+  text such as `a<b` is not flagged; only strings matching the tag-shape regex are rejected.
+
+**Lint errors:**
+- `description is required`
+- `description must not exceed 1024 characters (got N)`
+- `description must not contain XML tags (e.g. <example>)`
+
+---
+
+## 3. `audience` Field
+
+**Rule:** Must be exactly the string `public` or `private`. Any other value (including missing) is an error.
+
+```yaml
+audience: public   # shipped in dist/public/ bucket
+audience: private  # shipped in dist/private/ bucket only
+```
+
+**Lint error if wrong:** `audience must be public|private`
+
+**Build behavior:**
+- `public` skills are copied to `dist/public/<skill-name>/`
+- `private` skills are copied to `dist/private/<skill-name>/`
+- `plugins.private` must be set in `motto.yaml` before any private skill can be built
+
+---
+
+## 4. Body Spine — Two Independent Checks
+
+The skill body (the Markdown after the closing `---` delimiter) must satisfy two checks. Both run independently — both errors are reported even if both fail at once.
+
+**Check 1 — H1 title:** The first non-blank line of the body must match `^# \S` (an H1 heading with at least one non-space character after `# `).
+
+```markdown
+# My Skill Title
+```
+
+**Lint error if missing:** `body must begin with an H1 title line (# Title) as its first non-blank line`
+
+**Check 2 — Role line:** The body must contain at least one line that starts with `**Role:` (multiline match).
+
+```markdown
+**Role:** You are a hands-on guide who walks the author through...
+```
+
+The Role line content after `:` is not validated. An empty `**Role:**` passes the regex but produces unusable agent instruction content. Write Role lines as complete, behavioral sentences.
+
+**Lint error if missing:** `body must contain a **Role:** line`
+
+---
+
+## 5. `shared_references` Field
+
+**Rule:** Optional. When present, must be a YAML array of strings. Each entry must be a safe basename.
+
+```yaml
+shared_references:
+  - skill-schema
+  - another-reference
+```
+
+**Per-entry rules:**
+- Must NOT contain `/` or `.` — bare basenames only, no path separators or extensions
+- Must correspond to an existing `shared/references/<entry>.md` file
+
+**Per-entry lint errors:**
+- `shared_references entry "X" is an unsafe basename (must not contain "/" or ".")`
+- `shared_references entry "X" not found in shared/references/`
+
+**Build behavior:** `motto build` copies `shared/references/<entry>.md` into each skill's `dist/<audience>/<skill-name>/references/` directory, making the skill self-contained.
+
+**Collision guard:** If a skill already has a local `references/<entry>.md`, build will report a collision and stop.
+
+---
+
+## 6. `template` and `dependencies` Fields
+
+These fields are accepted and passed through verbatim. They are NOT validated in Motto v0.0.2.
+
+```yaml
+template: some-template
+dependencies:
+  - another-skill
+```
+
+---
+
+## 7. Frontmatter Envelope
+
+Every SKILL.md must open with a bare `---` on line 1 and close with a matching bare `---`.
+
+```
+---
+name: my-skill
+description: What this skill does and when to use it.
+audience: public
+---
+
+# My Skill Title
+
+**Role:** You are...
+```
+
+**Rules:**
+- The opening `---` must be the very first line (no blank lines, no BOM — BOM is stripped automatically).
+- A matching closing `---` is required.
+- YAML between the delimiters is parsed with the `yaml` v2 library (YAML 1.2 core schema) — `yes`/`no`/`on`/`off` are NOT treated as booleans.
+- A stray `---` inside the body is flagged only if the content between it and the body start parses as a clean, non-empty YAML mapping. Wrapping example SKILL.md blocks in fenced code blocks avoids this edge case.
+
+**Lint errors:**
+- `missing frontmatter: file must begin with a '--- ... ---' block`
+- `unterminated frontmatter: no closing '---' delimiter found`
+- `stray '---' delimiter in frontmatter: the block must contain exactly one closing '---'`