SkillValidator + langchain skills lint — catch broken SKILL.md files before runtime

Talking Shop
1

Hi everyone! :waving_hand:

I’ve been building agents with the Deep Agents Skills system and ran into a frustrating issue: when a SKILL.md is malformed (wrong name format, missing description, invalid YAML…), the agent silently ignores the skill with no actionable error message.

I’d love to propose a small, self-contained feature to fix this: a SkillValidator and a langchain skills lint CLI command.

:fire: The Problem

SKILL.md files must follow a strict schema:

  • name → lowercase, alphanumeric + hyphens, max 64 chars
  • description → required, max 1024 chars (agent reads this at startup)

Currently, mistakes are invisible until runtime. For example, this is a real scenario when you have 10+ skills in a team setting:

skills/

code-review/SKILL.md ← missing `description`

web-search/SKILL.md ← name has uppercase: “Web_Search”

sql-generator/SKILL.md ← description is 1200 chars (too long)

The agent will either skip these skills silently or misbehave — no feedback at all.

:white_check_mark: Proposed Solution

1. Python API

python

from langchain.skills.validator import validate_skill_directory

reports = validate_skill_directory(“./skills”)

for report in reports:

if not report.is_valid:

    print(f"❌ {report.skill_path}")

for error in report.errors:

        print(f"   ERROR: {error}")

for warning in report.warnings:

        print(f"   WARNING: {warning}")

2. CLI Command

bash

$ langchain skills lint ./skills

:cross_mark: skills/code-review/SKILL.md

ERROR: Missing required field: `description`

:cross_mark: skills/web-search/SKILL.md

ERROR: `name` must be lowercase alphanumeric with hyphens. Got: “Web_Search”

:warning: skills/sql-generator/SKILL.md

WARNING: `description` exceeds 1024 characters (1200). Agent context may be impacted.

3 skill(s) checked — 2 error(s), 1 warning(s)

Useful flags:

  • --fail-fast → stop at first error (great for CI pipelines)
  • --format json → machine-readable output for tooling

:triangular_ruler: Validation Rules

Rule Severity
Missing name or description :cross_mark: ERROR
name contains invalid characters (e.g. uppercase, spaces) :cross_mark: ERROR
name exceeds 64 characters :cross_mark: ERROR
Invalid / unparseable YAML frontmatter :cross_mark: ERROR
No SKILL.md found in skill directory :cross_mark: ERROR
description exceeds 1024 characters :warning: WARNING

:package: Implementation Scope

This is 100% additive — no breaking changes.

:warning: Repo question (see below): The Skills system is primarily documented under Deep Agents. I’m not yet sure whether this belongs in langchain-ai/langchain or langchain-ai/deepagents. I’ve listed a tentative file layout below — maintainers, please correct me!

Tentative layout (if in langchain-ai/langchain):

File What
libs/langchain/langchain/skills/validator.py Core validation logic
libs/langchain/langchain/skills/schemas.py Pydantic schema for frontmatter
libs/langchain/tests/unit_tests/skills/test_validator.py Unit tests
libs/cli/langchain_cli/namespaces/skills.py langchain skills lint CLI command

Tentative layout (if in langchain-ai/deepagents):

File What
deepagents/skills/validator.py Core validation logic
deepagents/skills/schemas.py Pydantic schema for frontmatter
tests/skills/test_validator.py Unit tests
cli/namespaces/skills.py langchain skills lint CLI command

No new dependencies — uses pydantic, pyyaml, and typer, which are already in the codebase.

:red_question_mark: Questions for the maintainers

Before I open a PR, I’d love to align on a few design decisions:

  1. [Most important] Which repository should host this? The Skills system is documented under Deep Agents, which suggests the validator might belong in langchain-ai/deepagents rather than langchain-ai/langchain. However, the CLI (langchain skills lint) would naturally live in langchain-ai/langchain alongside langchain-cli. Which repo (or both) is the right target for this contribution?
  2. Is libs/langchain/langchain/skills/ the right module path, or should this live in langchain-core?
  3. Preferred CLI command name: langchain skills lint or langchain skill validate?
  4. Are there planned frontmatter fields beyond name and description that I should account for?
  5. Should warnings produce a non-zero exit code by default (strict mode), or only errors?

Happy to implement this and open a PR once the approach is aligned. Looking forward to the community’s feedback! :folded_hands:

— Amine