Overview

When skills are created or edited via skill_manage, there are currently no automated quality checks. A skill with broken Python, malformed YAML frontmatter, or missing referenced files will be silently accepted and may fail at runtime.

Adding lightweight validation would catch common issues early and improve skill reliability.

What to Validate

On create/edit (skill_manage):

• YAML frontmatter is well-formed and parseable
• Required fields present (name, description)
• Referenced files in references/, templates/, scripts/, assets/ actually exist
• Python files (.py) in the skill directory pass ast.parse() (syntax check)
• No broken symlinks

Optional (configurable):

• Skill name matches directory name
• Tags are valid strings
• Description is non-empty and meaningful

Implementation Ideas

1. Inline validation in skill_tools.py — Run checks after skill_manage create/edit and warn the agent if issues are found (non-blocking, just warnings in the return message).

2. Standalone CLI command — hermes skill validate <name> or hermes skill validate --all to lint all installed skills. Useful for bulk checks after importing skills.

3. Pre-load validation — When skill_view loads a skill, optionally flag issues (e.g., "Warning: scripts/validate.py referenced but not found").

Scope

This should be lightweight — basic syntax and structure checks, not semantic analysis. The goal is catching obvious mistakes (typos in YAML, syntax errors in scripts, missing files), not evaluating whether a skill is good.

Prior Art

Inspired by the validate_skill concept from PR #240, which used ast.parse() to check Python files in skill directories.