---

name: faf-format-validator description: Validate both YAML frontmatter formats (SKILL.md for Claude Code) and IANA-registered project.faf formats. Use when user asks "validate my skill", "check YAML format", "is my SKILL.md correct", or needs to verify format compliance for either Claude Code skills or project.faf files. allowed-tools: Read, Bash, Grep

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:

Copy---
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:

Copyformat:
  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:

Copy# 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

Copycat skills/faf-teacher/SKILL.md

1. Check YAML frontmatter

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

1. Validate fields

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

1. Check markdown content

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

1. Report results

Copy✅ 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

Copyfaf validate

1. Check IANA compliance

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

1. Verify version

Copyformat:
  version: 3.0.0  # Must be 3.0.0+

1. Check required sections

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

1. Calculate score

Copyfaf score

1. Report results

Copy✅ 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

Copy---
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

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

Solution: Use correct file extension

ERROR 3: Missing IANA registration

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

Solution: Run faf migrate to upgrade

---

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:

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

4. Check markdown content:

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

Result:

Copy✅ 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:

   Copy✅ 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:

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

Result:

Copy✅ 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:

Copy---
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:

Copy❌ 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:

CopyYAML 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:

CopyPure YAML (structured data)
No markdown

Extension: .faf

---

Validation Commands

For SKILL.md

Copy# 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

Copy# 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:

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

Right:

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

Mistake 2: Using SKILL.md as project.faf

Wrong:

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

Right:

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

Mistake 3: Mixing formats

Wrong:

Copy---
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:

Copy# 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:

Copyfaf validate

Fix: Ensure IANA media type present:

Copyformat:
  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."