@modus-data/skill-agent-manifests

CLI validator and TypeScript schema for the Modus Skills and Agents YAML manifest format. Used by the GitHub Actions workflow that ships in every Modus-connected repository to validate manifest files on every pull request, and by Modus internally to keep both directions of sync honest.

Usage

npx --yes @modus-data/skill-agent-manifests@1 validate \
  .modus/skills/*.yaml \
  .modus/agents/*.yaml

Exit codes:

• 0 — every file passed.
• 1 — one or more files failed (per-file Zod errors AND/OR cross-file errors — duplicate externalUid, unresolved cross-references, filename ↔ slug mismatches).
• 64 — usage error (no files supplied).

The validator expects files to live under .modus/skills/<slug>.yaml or .modus/agents/<slug>.yaml — the layout your Modus-managed repo already uses.

Validation: block-at-CI thumb rule

The validator's job is to catch every problem that's diagnosable from the customer's repo alone, at PR time, so the customer sees the failure before the change reaches main. Two layers of checks:

1. Per-file: Zod structural validation, filename ↔ slug pattern, recognised apiVersion and kind.
2. Cross-file: duplicate metadata.externalUid across files, cross-references (skill supervision.subordinates, agent agentSelection.agents) resolving to siblings in the repo.

When the CLI is invoked with more than one file, the cross-file checks run automatically.

Recommended CI setup

Add this to .github/workflows/validate-modus-manifests.yml (or the equivalent in your CI system):

name: Validate Modus manifests
on:
  pull_request:
    paths: ['.modus/**']
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - name: Validate
        run: |
          shopt -s nullglob
          files=( .modus/skills/*.yaml .modus/agents/*.yaml )
          if [ ${#files[@]} -eq 0 ]; then echo "no manifests"; exit 0; fi
          npx --yes @modus-data/skill-agent-manifests@1 validate -- "${files[@]}"

The non-zero exit on validation failure fails the job, blocks the PR, and the customer fixes the YAML before merging.

Public API

| Function | Input | Output | Use case | |----------|-------|--------|----------| | parseSkillManifest(yaml, path?) | YAML string | SkillManifest | Validate + parse one skill file | | parseAgentManifest(yaml, path?) | YAML string | AgentManifest | Validate + parse one agent file | | serializeSkillManifest(manifest) | SkillManifest | YAML string | Re-emit a parsed skill manifest | | serializeAgentManifest(manifest) | AgentManifest | YAML string | Re-emit a parsed agent manifest | | validateRepo({files}) | {path, content}[] | {errors} | Cross-file validation pass |

serializeSkill / serializeAgent take the internal SerializableSkillRecord / SerializableAgentRecord shapes used by Modus's apply path; the *Manifest variants above take the parsed SkillManifest / AgentManifest shapes the CLI/customer side uses.

License

MIT