MarkdownSchema

Create and validate .mdschema files that enforce frontmatter fields and heading structure across forge artifacts. Wraps the mdschema CLI with forge-specific conventions.

When editing any markdown file

See MarkdownSchema.md — the rule for conforming to a sibling .mdschema when one exists in the file's directory.

Workflow Routing

| Workflow | Trigger | Section | |--------------|------------------------------------------------|------------------------------------------| | Create | "create schema", "add schema", "new schema" | Create Workflow | | Derive | "derive schema", "infer schema" | @Derive.md | | Validate | "validate", "check", "lint schema" | @Validate.md |

Conventions

Schema Filename

Always .mdschema (no .yml extension). Lives alongside the files it validates:

skills/.mdschema          # validates skills/*/SKILL.md
agents/.mdschema          # validates agents/*.md
.mdschema                 # validates *.md in current directory

Field Requirements by Artifact Type

| Artifact | Required fields | Optional fields | max_depth | |--------------|----------------------------------|------------------|-----------| | Skill | name, description, version | argument-hint | 3 | | Agent | name, description, version | -- | 3 | | Project docs | (frontmatter optional) | -- | 4 |

All schemas enforce no_skip_levels: true.

Reference Schemas

Skill schema:

frontmatter:
    fields:
        - name: name
        - name: description
        - name: version

heading_rules:
    no_skip_levels: true
    max_depth: 3

Agent schema:

frontmatter:
    fields:
        - name: name
        - name: description
        - name: version

heading_rules:
    no_skip_levels: true
    max_depth: 3

Project docs schema:

frontmatter:
    optional: true

heading_rules:
    no_skip_levels: true
    max_depth: 4

---

Create Workflow

Step 1: Determine target

Identify the directory and artifact type:

• skills/ directory with */SKILL.md files → skill schema
• agents/ directory with *.md files → agent schema
• Project root or doc directory → project docs schema

If ambiguous, ask the user.

Step 2: Check for existing schema

Look for .mdschema in the target directory. If one exists, show it and ask whether to replace or update.

Step 3: Write the schema

Use the reference schema for the detected artifact type from the conventions table.

Write .mdschema to the target directory using the Write tool.

Step 4: Validate

Run validation immediately to confirm the schema works:

mdschema check "<glob>" --schema <path>/.mdschema

Glob patterns by artifact type:

• Skills: "skills/*/SKILL.md"
• Agents: "agents/*.md"
• Project docs: "*.md"

Report results. If violations are found, present them and ask whether to fix the documents or adjust the schema.

---

@Derive.md

@Validate.md

Constraints

• Schema files are always named .mdschema -- never .mdschema.yml or .mdschema.yaml
• Never make frontmatter fields optional unless the artifact type genuinely doesn't use them -- version should be required for skills and agents to catch nesting errors
• no_skip_levels is always true -- no exceptions
• If mdschema is not installed, tell the user: brew install jackchuka/tap/mdschema

Sources

• https://github.com/jackchuka/mdschema