Forge-core MarkdownSchema

Create, derive, and validate .mdschema files for markdown documents. USE WHEN create schema, add schema, derive schema, validate schema, check schema, mdschema, lint schema, heading rules, frontmatter validation.

install

source · Clone the upstream repo

git clone https://github.com/N4M3Z/forge-core

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/N4M3Z/forge-core "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/MarkdownSchema" ~/.claude/skills/n4m3z-forge-core-markdownschema && rm -rf "$T"

manifest: skills/MarkdownSchema/SKILL.md

source content

MarkdownSchema

Create and validate

.mdschema

files that enforce frontmatter fields and heading structure across forge artifacts. Wraps the

mdschema

CLI with forge-specific conventions.

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

Agent

name

description

version

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

mdschema

is not installed, tell the user:

brew install jackchuka/tap/mdschema