block/buzz · warning · ValidationDiagnostic::Warning

skill {label}: name "{name_str}" differs from directory name

Error message

skill {label}: name "{name_str}" differs from directory name "{dir_name}"

What it means

Advisory check over every skill directory referenced by a loaded persona: the YAML front-matter name: field in SKILL.md must equal the skill's directory name. A mismatch is reported as a warning; loading continues, but tooling that resolves or invokes skills by directory name may disagree with the declared name.

Source

Thrown at crates/buzz-persona/src/validate.rs:426

            Ok(v) => v,
            Err(_) => continue,
        };

        let mapping = match yaml_val.as_mapping() {
            Some(m) => m,
            None => continue,
        };

        if let Some(name_val) = mapping.get(serde_yaml::Value::String("name".into())) {
            if let Some(name_str) = name_val.as_str() {
                if let Some(dir_name) = skill_dir.file_name().and_then(|n| n.to_str()) {
                    if name_str != dir_name {
                        let label = skill_dir
                            .strip_prefix(pack_dir)
                            .unwrap_or(skill_dir)
                            .display()
                            .to_string();
                        report.warn(format!(
                            "skill {label}: name \"{name_str}\" differs from directory name \"{dir_name}\""
                        ));
                    }
                }
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn exit_code_clean() {
        let report = ValidationReport::default();
        assert_eq!(report.exit_code(), 0);
    }

View on GitHub (pinned to 934f3325c3)

Solutions

1. Make the SKILL.md name: field byte-identical to the directory name — pick one as canonical and align the other
2. Add a pack CI lint that fails on name/dir mismatches before publishing
3. When renaming a skill, update both the directory and every persona manifest that references it

Example fix

# before
skills/code-review/SKILL.md → name: review-code

# after
skills/code-review/SKILL.md → name: code-review

import { readFileSync, readdirSync } from "node:fs";
for (const dir of readdirSync("pack/skills", { withFileTypes: true })) {
  if (!dir.isDirectory()) continue;
  const md = readFileSync(`pack/skills/${dir.name}/SKILL.md`, "utf8");
  const name = /^name:\s*(.+)$/m.exec(md)?.[1]?.trim();
  if (name !== dir.name) throw new Error(`skill ${dir.name}: SKILL.md name "${name}" differs from directory name`);
}

When it happens

Trigger: Renaming a skill directory without updating the name: field in SKILL.md (or vice versa); copying a skill folder to a new name while keeping the original front-matter; generated packs where directory names are slugified differently from the declared name (spaces, casing).

Common situations: Hand-authored persona packs; forks/renames of shared skills; name fields containing spaces or mixed case that cannot survive as a directory name.

Related errors

• plugin.json unknown key "{key}"
• plugin.json defaults: unknown key "{key}"
• plugin.json defaults.triggers: unknown key "{key}"
• moderation notice recipient must be a 32-byte pubkey, got {}
• bundled model-capabilities.json must parse

AI-assisted analysis of block/buzz@934f3325c3 (2026-08-20). Data as JSON: /api/errors/0e32282781c558cf. Report an issue: GitHub.