---
name: bilal140202/faf-format-inspector
source: https://app.decimal.ai/s/bilal140202-faf-format-inspector@1/SKILL.md
source_sha256: 835b19f0d057
---

# 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:**
```yaml
---
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:**
```yaml
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:**

```bash
# 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**
```bash
cat skills/faf-teacher/SKILL.md
```

2. **Check YAML frontmatter**
```yaml
# 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**
```bash
faf validate
```

2. **Check IANA compliance**
```yaml
format:
  iana_media_type: application/vnd.faf+yaml  # Required
```

3. **Verify version**
```yaml
format:
  version: 3.0.0  # Must be 3.0.0+
```

4. **Check required sections**
- format (✅)
- project (✅)
- architecture (✅)

5. **Calculate score**
```bash
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**
```yaml
---
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**
```yaml
# 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

| Check | Required | Common Issues |
|-------|----------|---------------|
| **YAML frontmatter** | ✅ Yes | Forgot closing `---` |
| **name field** | ✅ Yes | CamelCase instead of kebab-case |
| **description field** | ✅ Yes | Too short (<50 chars) |
| **allowed-tools** | ✅ Yes | Invalid tool names |
| **Markdown content** | ✅ Yes | No sections after frontmatter |
| **Purpose section** | ⚠️ Recommended | Missing purpose statement |
| **Examples** | ⚠️ Recommended | No usage examples |

### project.faf Validation

| Check | Required | Common Issues |
|-------|----------|---------------|
| **Valid YAML** | ✅ Yes | Syntax errors, tabs vs spaces |
| **format.version** | ✅ Yes | Old version (v2.x, v1.x) |
| **iana_media_type** | ✅ Yes | Missing or incorrect |
| **project section** | ✅ Yes | Empty or missing |
| **architecture** | ✅ Yes | Undefined architecture type |
| **Podium score** | ⚠️ Quality | Low score (<40%) |

---

## 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:
   ```bash
   ✅ 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:**
```yaml
---
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

```bash
# 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

```bash
# 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:**
```yaml
# In repository root: SKILL.md
---
name: my-project  # ❌ This is not a skill
---
```

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

### Mistake 3: Mixing formats

**Wrong:**
```yaml
---
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:**
```bash
# 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:**
```bash
faf validate
```

**Fix:** Ensure IANA media type present:
```yaml
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."**