Skip to content

feat: skill validate and fix CLI commands #345

@christso

Description

@christso

Summary

Add `allagents skill validate` and `allagents skill fix` commands for CI/CD pipelines in skills repositories.

Motivation

Research into WiseTechGlobal/Tools.WtgCopilotSkills showed their sync script validates YAML frontmatter fields, strips invalid fields, converts arrays to comma-separated strings, and removes BOM characters. This validation belongs in CI/CD for skills repos, not at sync time.

Proposed Solution

`allagents skill validate [path]`

  • Validate YAML frontmatter fields against known schema
  • Check for invalid/unsupported fields
  • Verify required fields (`name`, `description`) are present
  • Report BOM characters or encoding issues
  • Exit non-zero on errors (CI-friendly)
  • Default path: current directory (scans recursively for `SKILL.md` files)

`allagents skill fix [path]`

  • Auto-fix common issues:
    • Strip BOM characters
    • Remove invalid frontmatter fields
    • Normalize field formats (e.g., array → comma-separated string where required)
  • `--dry-run` mode to preview changes without writing

Usage

```bash

In CI pipeline

allagents skill validate ./skills/

Local development

allagents skill fix ./skills/ --dry-run
allagents skill fix ./skills/
```

Implementation Notes

  • Existing validation logic lives in `src/validators/skill.ts`:
    • `validateSkill()` — validates a single skill file
    • `validateAllSkills()` — validates all skills in a directory
    • `parseSkillMetadata()` — parses YAML frontmatter from skill content
  • Skill metadata parsing also in `src/core/skills.ts` and `src/core/repo-skills.ts`
  • CLI commands are in `src/cli/commands/` — existing `plugin-skills.ts` handles skill listing
  • Add new `skill.ts` command file (or extend `plugin-skills.ts`)
  • The `fix` command should reuse the same validation logic but write corrections back to files
  • Consider structured output (`--json`) for CI integration

Acceptance Criteria

  • `allagents skill validate ./path` scans for `SKILL.md` files and reports validation errors
  • Exits with non-zero code when errors found (CI-friendly)
  • Validates: required fields present, no unknown fields, correct field types, no BOM
  • `allagents skill fix ./path` auto-corrects fixable issues
  • `allagents skill fix --dry-run` previews changes without writing
  • Clear error output showing file path, line/field, and issue description
  • Works on both flat (`skills/foo.md`) and directory (`skills/foo/SKILL.md`) layouts

Context

This is a CI/CD concern for skills repo maintainers, not a sync-time concern. Keeps AllAgents sync fast and pushes validation left to where skills are authored.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status

    Backlog

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions