Summary

The skills documentation rewrite in commit a3fbaa5a (PR docs(skills): rewrite all skills to agentskills.io spec and add 9 new skills) uses YAML block scalar modifier >- (folded with strip-chomping) in the description field of all 19 skills. The SKILL.md parser explicitly rejects modifier variants — only plain > and | are supported.

Root Cause

In crates/zeph-skills/src/loader.rs, detect_block_scalar() returns Err for any value starting with > or | that is NOT exactly > or |:

v if v.starts_with('>') || v.starts_with('|') => Err(SkillError::Invalid(format!(
    "YAML block scalar modifiers are not supported (got '{v}'): \
     use plain '>' or '|' without chomping or indentation indicators"
))),

When description: >- is encountered, the parser emits WARN frontmatter key 'description': invalid skill: YAML block scalar modifiers are not supported (got '>-') and skips the field. load_skill_meta then fails with missing 'description' in frontmatter of ..., causing the registry to skip the skill file.

Impact

19 out of 24 skills in .zeph/skills/ fail to load:

api-request, archive, code-analysis, cron, database, docker, file-ops,
git, github, json-yaml, network, process-management, qdrant, regex,
ssh-remote, system-info, text-processing, web-scrape, web-search

The 9 new skills (archive, cron, database, json-yaml, network, process-management, qdrant, regex, ssh-remote, text-processing) have no fallback and are completely unavailable.

For existing users: normalize_legacy_runtime_defaults() migrates the legacy paths = [".zeph/skills"] to ~/.config/zeph/skills/ (managed dir). This masked the regression — old skill versions without >- are loaded from the managed dir. New skills are silently unavailable.

For fresh installs or users who explicitly set paths = [".zeph/skills"]: all 19 skills fail silently.

Reproduction

mkdir -p /tmp/test-skills/archive
cat > /tmp/test-skills/archive/SKILL.md << 'EOF2'
---
name: archive
description: >-
  Test skill using >- modifier.
  Use when the user asks to archive files.
---
# Archive
EOF2

# Run with RUST_LOG=warn — shows WARN for >- rejection
echo 'test' | RUST_LOG=warn ./target/debug/zeph --config your-config.toml 2>&1 | grep frontmatter

Output:

WARN zeph_skills::loader: frontmatter key 'description': invalid skill: YAML block scalar modifiers are not supported (got '>-'): use plain '>' or '|' without chomping or indentation indicators
WARN zeph_skills::registry: skipping .../archive/SKILL.md: invalid skill: missing 'description' in frontmatter of ...

Fix Options

Option A (preferred): Convert all description: >- to description: > in .zeph/skills/*/SKILL.md (19 files). The only semantic difference is trailing-newline stripping, which has no effect on skill matching.

Option B: Update the parser to support >- by treating it identically to > (strip trailing newline from collected text). This is safe since the chomping behavior only affects trailing whitespace.

Severity

HIGH — 9 new skills are completely unavailable; 10 existing skills silently fall back to stale versions from ~/.config/zeph/skills/. Fresh installs affected most severely.

Verified in CI-50 (2026-03-21)

• Isolated test skill with description: >- confirmed to emit WARN and fail to load
• 19 .zeph/skills/ entries with >- do not appear when pointing config directly at the directory
• Standard regression (97×53=5151, German FeedbackDetector @ 0.85, cross-session recall CI50_RECALL_KEY) ✅ — no new regressions in non-skill code