FAF Format Validator - Dual YAML Format Validation

Purpose

Validate two distinct YAML formats in the FAF ecosystem:

1. SKILL.md - YAML frontmatter for Claude Code skills
2. project.faf - IANA-registered format for project DNA

The Goal: Ensure both tooling (Skills) and infrastructure (project.faf) maintain format integrity.

When to Use

This skill activates when the user:

• Asks "Validate my skill format"
• Says "Check my SKILL.md"
• Asks "Is my project.faf valid?"
• Says "Verify YAML formats"
• Needs to compare SKILL.md vs project.faf format
• Creates new skills and wants validation

Trigger Words: validate, check format, SKILL.md, project.faf, YAML, frontmatter, format compliance

The Two Formats

Format 1: SKILL.md (Claude Code Skills)

Purpose: Configure Claude Code skill activation

Required Structure:

---
name: skill-name
description: One-sentence description with trigger words
allowed-tools: Tool1, Tool2, Tool3
---

# Skill Title

## Purpose
...

Required Fields:

• name

  - Skill identifier (kebab-case)

• description

  - Comprehensive description with trigger phrases

• allowed-tools

  - List of tools the skill can use

Optional Fields:

• version

  - Skill version (semantic)

• author

  - Skill creator

Validation Checks:

1. ✅ YAML frontmatter delimited by

   ---

2. ✅

   name

   field present (lowercase, kebab-case)
3. ✅

   description

   field present (100+ characters recommended)
4. ✅

   allowed-tools

   field present
5. ✅ Markdown content follows frontmatter
6. ✅ Content has clear sections (Purpose, When to Use, etc.)

Format 2: project.faf (IANA-Registered)

Purpose: Universal project DNA for ANY AI

Required Structure:

format:
  name: FAF
  version: 3.0.0
  iana_media_type: application/vnd.faf+yaml

project:
  name: Project Name
  version: 1.0.0

architecture:
  type: web-app
  stack: []

Required Fields:

• format.name

  - Must be "FAF"

• format.version

  - Must be "3.0.0" or higher

• format.iana_media_type

  - Must be "application/vnd.faf+yaml"

• project.name

  - Project name

• architecture.type

  - Architecture type

Validation Checks:

1. ✅ Valid YAML syntax
2. ✅ Format version 3.0.0+
3. ✅ IANA media type present
4. ✅ Required top-level sections
5. ✅ Architecture defined
6. ✅ No SKILL.md frontmatter mixed in

How It Works

Step 1: Detect Format Type

Auto-detection logic:

# Check if SKILL.md (frontmatter)
if file contains "---" at line 1 AND markdown content:
  → Validate as SKILL.md format

# Check if project.faf (IANA)
if file has .faf extension OR contains "iana_media_type":
  → Validate as project.faf format

# Check if both (ERROR)
if file has both frontmatter AND iana_media_type:
  → ERROR: Mixed formats detected

Step 2: Validate SKILL.md Format

Validation workflow:

1. Read file

cat skills/faf-teacher/SKILL.md

2. Check YAML frontmatter

# Must start with ---
# Must have name, description, allowed-tools
# Must end with ---

3. Validate fields

• Name: lowercase, kebab-case, no spaces
• Description: 50+ characters, includes trigger words
• Tools: Valid Claude Code tools only

4. Check markdown content

• Purpose section exists
• "When to Use" section exists
• Examples provided

5. Report results

✅ SKILL.md Format Valid

Name: faf-teacher
Description: 150 characters (✅ comprehensive)
Tools: Read, WebFetch (✅ valid)
Sections: 8 found (✅ complete)

Step 3: Validate project.faf Format

Validation workflow:

1. Use faf-cli validation

faf validate

2. Check IANA compliance

format:
  iana_media_type: application/vnd.faf+yaml  # Required

3. Verify version

format:
  version: 3.0.0  # Must be 3.0.0+

4. Check required sections

• format (✅)
• project (✅)
• architecture (✅)

5. Calculate score

faf score

6. Report results

✅ project.faf Format Valid

Version: 3.0.0 (✅ current)
IANA Media Type: application/vnd.faf+yaml (✅ registered)
Score: 72% (🥇 Gold tier)
Required Fields: 10/10 present

Step 4: Detect Format Conflicts

Common errors:

ERROR 1: Mixed formats

---
name: my-project  # ❌ SKILL.md frontmatter
description: test
---

format:  # ❌ project.faf structure
  iana_media_type: application/vnd.faf+yaml

Solution: Choose one format - either SKILL.md OR project.faf

ERROR 2: Wrong extension

project.md  # ❌ Should be project.faf
SKILL.faf   # ❌ Should be SKILL.md

Solution: Use correct file extension

ERROR 3: Missing IANA registration

# project.faf without iana_media_type
format:
  name: FAF
  version: 3.0.0
  # ❌ Missing iana_media_type

Solution: Run

faf migrate

Validation Matrix

SKILL.md Validation

---

project.faf Validation

Examples

Example 1: Validate SKILL.md

User: "Check if my faf-teacher skill is valid"

Skill Activates:

1. Read file:

   skills/faf-teacher/SKILL.md

2. Parse YAML frontmatter
3. Validate fields:

   ✅ name: faf-teacher (valid)
   ✅ description: 150 chars (comprehensive)
   ✅ allowed-tools: Read, WebFetch (valid)
   

4. Check markdown content:

   ✅ Purpose section found
   ✅ "When to Use" section found
   ✅ 5 examples provided
   

Result:

✅ SKILL.md Format Valid

Skill: faf-teacher
Quality: Championship grade
Sections: 8/8 required sections
Trigger words: 12 identified

Example 2: Validate project.faf

User: "Is my project.faf valid?"

Skill Activates:

1. Run

   faf validate

2. Check output:

   ✅ Valid YAML syntax
   ✅ Format version: 3.0.0
   ✅ IANA media type: application/vnd.faf+yaml
   ✅ All required fields present
   

3. Run

   faf score

4. Show results:

   Score: 68% (🥈 Silver tier)
   
   Missing:
   - Testing documentation
   - API documentation
   

Result:

✅ project.faf Valid (Silver tier)

Next: Run `faf enhance` to reach Gold (70%+)

Example 3: Detect Mixed Format

User: "Why isn't this working?"

File content:

---
name: my-project
---

format:
  iana_media_type: application/vnd.faf+yaml

Skill Activates:

1. Detects YAML frontmatter (

   ---

   )
2. Detects IANA format (

   iana_media_type

   )
3. ERROR: Mixed formats

Result:

❌ Format Conflict Detected

You're mixing two different YAML formats:
- SKILL.md (frontmatter) - For Claude Code skills
- project.faf (IANA) - For project DNA

Choose one:

Option 1 - Creating a skill?
→ Use SKILL.md format
→ File: skills/skill-name/SKILL.md

Option 2 - Describing project?
→ Use project.faf format
→ File: project.faf
→ Run: faf init

Format Comparison Guide

When to Use SKILL.md

Use SKILL.md when:

• Creating Claude Code skills
• Adding to

  ~/.config/claude-code/skills/

• Configuring skill activation
• Writing instructions for Claude

Structure:

YAML frontmatter (metadata)
+
Markdown content (instructions)

Extension:

.md

When to Use project.faf

Use project.faf when:

• Describing project architecture
• Making project AI-readable
• Creating persistent context
• Supporting ANY AI tool

Structure:

Pure YAML (structured data)
No markdown

Extension:

.faf

Validation Commands

For SKILL.md

# Manual validation
cat skills/faf-teacher/SKILL.md | head -10

# Check frontmatter
grep -A 5 "^---$" skills/faf-teacher/SKILL.md | head -6

# Verify tools
grep "allowed-tools:" skills/faf-teacher/SKILL.md

For project.faf

# faf-cli validation (recommended)
faf validate

# Manual YAML check
cat project.faf | head -20

# Check IANA registration
grep "iana_media_type" project.faf

# Get score
faf score

Common Mistakes

Mistake 1: Using project.faf as SKILL.md

Wrong:

skills/faf-teacher/project.faf  # ❌ Wrong format

Right:

skills/faf-teacher/SKILL.md     # ✅ Correct

Mistake 2: Using SKILL.md as project.faf

Wrong:

# In repository root: SKILL.md
---
name: my-project  # ❌ This is not a skill
---

Right:

# In repository root: project.faf
format:
  iana_media_type: application/vnd.faf+yaml  # ✅ Correct

Mistake 3: Mixing formats

Wrong:

---
format:  # ❌ Can't mix frontmatter + IANA
  iana_media_type: application/vnd.faf+yaml
---

Right: Pick one format, use it correctly

Troubleshooting

Issue: "Invalid YAML frontmatter"

Symptom: Skill won't load in Claude Code

Check:

# Must start with ---
head -1 skills/skill-name/SKILL.md

# Must have closing ---
grep -n "^---$" skills/skill-name/SKILL.md

Fix: Ensure frontmatter is properly delimited

Issue: "project.faf not recognized"

Symptom: AI doesn't understand project

Check:

faf validate

Fix: Ensure IANA media type present:

format:
  iana_media_type: application/vnd.faf+yaml

Issue: "Mixed format error"

Symptom: File has both frontmatter and IANA format

Fix: Separate into two files:

1. SKILL.md (if creating a skill)
2. project.faf (if describing project)

Related Skills

• faf-validate - Validates project.faf only (IANA format)
• faf-migrate - Upgrades old project.faf versions
• faf-init - Creates new project.faf files
• faf-teacher - Explains format differences

Key Principles

1. Two Formats, Two Purposes

SKILL.md:

• Tooling (how to build FAF files)
• Claude Code specific
• Frontmatter + Markdown

project.faf:

• Infrastructure (the project itself)
• Universal AI compatibility
• Pure YAML

2. Don't Mix Them

Each format serves a distinct role:

• Skills help CREATE project.faf
• project.faf contains PROJECT data
• Never combine them

3. Validate Early, Validate Often

For Skills:

• Check before installing
• Verify after editing
• Test activation

For project.faf:

• Validate after creation (

  faf validate

  )
• Score after enhancement (

  faf score

  )
• Migrate when needed (

  faf migrate

  )

Success Metrics

SKILL.md Validation:

• ✅ All required fields present
• ✅ Description comprehensive (100+ chars)
• ✅ Valid Claude Code tools only
• ✅ Clear markdown structure

project.faf Validation:

• ✅ IANA media type present
• ✅ Version 3.0.0+
• ✅ All required sections
• ✅ Score 40%+ (Bronze minimum)

Generated by FAF Skill: faf-format-validator v1.0.0 "Two formats. Two purposes. One ecosystem. Validate both."