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