## Why are we doing this work Three separate places will need to decide whether a `SKILL.md` can be published: the **Publish** scan, the merge request check, and the **Scaffold**. If each implements its own rules they drift, and an author gets told different things at different moments. The proof of concept already hit this. The **Validator** followed the specification and allowed a name of 1 to 64 characters, while `Ai::Catalog::Item` enforced 3 to 255 for every item type. A two-character name passed validation, the merge request widget reported the **Skill** as ready to publish, and the **Publish** then failed on save into an error bucket nothing renders — exactly the silent skip this work exists to remove. One ruleset is the fix, but only if everything that can reject a **Skill** defers to it. The matching change to `Ai::Catalog::Item`'s bounds belongs to slice B. This slice builds the one **Validator** that all three call. Its rules are not ours — they belong to the Agent Skills specification (https://agentskills.io/specification), vendored here as a JSON schema. ADR 0002 records why we vendor rather than fetch the specification at runtime or depend on the upstream library. Every **Rejection** the **Validator** produces carries a code and a message. Authors read those messages, and may end up scripting against those codes, which makes them the most expensive thing in this whole breakdown to change later. The slice is small, but it deserves careful review for that reason. Each **Rejection** is also categorised: `spec` for an Agent Skills specification rule, which an author can act on anywhere, or `platform` for a GitLab limit, which only means anything inside GitLab. Later slices use that split to decide what to show and where. There is no user-visible surface here and no feature flag check. Nothing reaches this code until a later slice calls it. ## Relevant links - Epic: https://gitlab.com/groups/gitlab-org/-/work_items/22961 - Proof of concept merge request: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/257276 — read this to see the whole thing end to end. The domain glossary (`CONTEXT.md`) and both architecture decision records (`docs/adr/`) live on that branch, not on `master`. - Agent Skills specification: https://agentskills.io/specification - Depends on: nothing. This is the first slice. ## Non-functional requirements - [ ] Documentation: Not required — no user-visible surface. ADR 0002 covers the vendoring decision. - [ ] Feature flag: Not required — unreachable until slice E or F lands. - [ ] Performance: Schema is compiled once and memoized on the class; validation runs against a string with no repository access. - [ ] Testing: Unit specs for `Validator` and `BlobCheck`, covering every **Rejection** code. ## Implementation plan - [ ] ~backend Add `app/validators/json_schemas/ai_catalog/skill_frontmatter_v1.json`. Require `name` (pattern `^[a-z0-9]+(-[a-z0-9]+)*$`, maxLength 64) and `description` (1-1024). Leave `license`, `compatibility`, `metadata` and `allowed-tools` optional. Set `additionalProperties: true` deliberately, and record why in a `$comment` alongside the retrieval date. - [ ] ~backend Add `ee/lib/gitlab/ai/catalog/skills/validator.rb` using `Gitlab::Utils::Executable`, so callers use `Validator.execute(path:, content:)`. It takes content and a path, never a repository. - [ ] ~backend Define `Validator::Rejection(path:, code:, message:, category:)` and `Validator::Result(path:, attributes:, rejections:)` with `#valid?`. - [ ] ~backend Accept only `---`-delimited YAML as front matter. `Gitlab::FrontMatter::PATTERN_UNTRUSTED_REGEX` also matches TOML and JSON blocks, which the specification does not allow, so check the delimiter and language explicitly. - [ ] ~backend Parse with `YAML.safe_load` and `permitted_classes: [Date, Time]`. - [ ] ~backend Derive error messages from the failing subschema rather than restating limits in Ruby, so raising a limit in the schema changes what the author reads without a second edit. - [ ] ~backend Check in Ruby that front matter `name` equals the parent directory name. JSON Schema draft-07 cannot express it, because the comparison spans the document and its file path. - [ ] ~backend Emit these codes: `no_frontmatter`, `invalid_yaml`, `frontmatter_not_a_mapping`, `name_directory_mismatch`, `invalid_<field>`, `invalid_frontmatter`. Key `invalid_<field>` on the top-level field, never the deepest one, so a code never varies with a key the author invented. - [ ] ~backend Add `ee/lib/gitlab/ai/catalog/skills/blob_check.rb` exposing `rejection_for(blob)`, returning a `platform`-category **Rejection** for Git LFS pointers, truncated blobs and non-UTF-8 content. Keep it separate from `Validator` so `Validator` stays free of repository concepts; both the scanner and the merge request resolver need it. - [ ] ~backend Add `ee/spec/lib/gitlab/ai/catalog/skills/validator_spec.rb` and `blob_check_spec.rb`.