agent-linter

Agent & Skill Linter

Agent ve skill dosyalarinin kalite kontrolu. Yanlis yapilandirilmis dosyalar runtime'da sessizce basarisiz olur -- linter bunu onler.

Agent Dosyasi Kurallari

Frontmatter (ZORUNLU)

---
name: agent-adi          # kebab-case, dosya adiyla AYNI olmali
description: Tek satir   # 20-200 karakter arasi
tools: ["Read", "Bash"]  # Gecerli tool listesi
model: opus              # Opsiyonel: opus | sonnet
---

Frontmatter Validasyonu

Kural	Kontrol	Hata Seviyesi
name mevcut	Frontmatter'da name var mi?	ERROR
name = dosya adi	name: sleuth == sleuth.md	ERROR
name kebab-case	code-reviewer OK, codeReviewer FAIL	ERROR
description mevcut	Bos olmamali	ERROR
description uzunlugu	20-200 karakter	WARN
tools array	String array olmali	ERROR
tools gecerli	Sadece bilinen tool isimleri	WARN
model gecerli	opus, sonnet veya bos	ERROR

Body Kurallari

Kural	Kontrol	Hata Seviyesi
System prompt var	Frontmatter'dan sonra icerik var	ERROR
50+ satir	Cok kisa agent tanimlari yetersiz	WARN
2000 satir max	Cok uzun dosyalar token israf eder	WARN
Markdown basliklar	En az 1 ## basligi var	WARN

Skill Dosyasi Kurallari

Frontmatter (ZORUNLU)

---
name: skill-adi          # kebab-case
description: Aciklama    # 20-300 karakter
---

Skill Validasyonu

Kural	Kontrol	Hata Seviyesi
Dosya adi	SKILL.md veya skill.md	ERROR
name mevcut	Frontmatter'da	ERROR
name = klasor adi	name: tdd-workflow == skills/tdd-workflow/	WARN
description mevcut	Bos olmamali	ERROR
Icerik var	Frontmatter'dan sonra en az 20 satir	WARN
Kod ornegi var	En az 1 code block	INFO

Lint Calistirma

Bash Script

#!/bin/bash
# scripts/lint-agents.sh

ERRORS=0
WARNS=0

lint_agent() {
  local file="$1"
  local name=$(basename "$file" .md)

  # Frontmatter kontrolu
  if ! head -1 "$file" | grep -q "^---"; then
    echo "ERROR: $file - frontmatter yok"
    ERRORS=$((ERRORS + 1))
    return
  fi

  # name field kontrolu
  local fm_name=$(sed -n '/^---$/,/^---$/p' "$file" | grep "^name:" | sed 's/name: *//')
  if [ -z "$fm_name" ]; then
    echo "ERROR: $file - name field yok"
    ERRORS=$((ERRORS + 1))
  elif [ "$fm_name" != "$name" ]; then
    echo "ERROR: $file - name '$fm_name' != dosya adi '$name'"
    ERRORS=$((ERRORS + 1))
  fi

  # description kontrolu
  local desc=$(sed -n '/^---$/,/^---$/p' "$file" | grep "^description:")
  if [ -z "$desc" ]; then
    echo "ERROR: $file - description yok"
    ERRORS=$((ERRORS + 1))
  fi

  # Uzunluk kontrolu
  local lines=$(wc -l < "$file")
  if [ "$lines" -lt 10 ]; then
    echo "WARN: $file - cok kisa ($lines satir)"
    WARNS=$((WARNS + 1))
  elif [ "$lines" -gt 2000 ]; then
    echo "WARN: $file - cok uzun ($lines satir)"
    WARNS=$((WARNS + 1))
  fi
}

echo "=== Agent Linter ==="
for f in agents/*.md; do
  lint_agent "$f"
done

echo ""
echo "=== Skill Linter ==="
for f in skills/*/SKILL.md skills/*/skill.md; do
  [ -f "$f" ] && lint_agent "$f"
done

echo ""
echo "Sonuc: $ERRORS error, $WARNS warning"
[ "$ERRORS" -gt 0 ] && exit 1 || exit 0

CI Entegrasyonu

# .github/workflows/lint-agents.yml
name: Agent & Skill Lint
on:
  pull_request:
    paths: ['agents/**', 'skills/**']

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: bash scripts/lint-agents.sh

Yaygin Hatalar

Hata	Ornek	Cozum
name/dosya uyumsuzlugu	name: codeReviewer dosya: code-reviewer.md	name'i kebab-case yap
Description cok kisa	description: Reviews code	Ne yaptigini detayla
Tools yanlis format	tools: Read, Bash	tools: ["Read", "Bash"]
Bos agent dosyasi	Sadece frontmatter, body yok	System prompt ekle
Duplicate name	2 agent ayni name'e sahip	Benzersiz isim ver
Skill klasor/name uyumsuz	name: tdd klasor: tdd-workflow/	Eslestir

Toplu Lint Raporu

# Tum agent'lari tara, rapor uret
cd ~/vibecosystem
bash scripts/lint-agents.sh 2>&1 | tee lint-report.txt

# Sadece ERROR'lari goster
grep "^ERROR" lint-report.txt

# Istatistik
echo "Agents: $(ls agents/*.md | wc -l)"
echo "Skills: $(ls skills/*/SKILL.md skills/*/skill.md 2>/dev/null | wc -l)"
echo "Errors: $(grep -c ERROR lint-report.txt)"
echo "Warnings: $(grep -c WARN lint-report.txt)"

vibecosystem Entegrasyonu

• verifier agent: Lint'i final quality gate'e ekle
• qa-engineer agent: Yeni agent/skill PR'larinda lint calistir
• self-learner agent: Lint hatalari pattern olarak ogren
• catalyst agent: Scaffold sırasinda lint-uyumlu dosya uret
• /commit skill: Commit oncesi agent/skill dosyalarini lint'le