## Why are we doing this work A **Skill**'s **Internal ID** is its directory name, and **Publish** matches repository files to **Catalog Items** by path: `PublishService#existing_by_path` keys existing items on `latest_version.def_path`. Renaming a **Skill** directory therefore reads as two unrelated events. The old path is gone, so its **Catalog Item** is soft-deleted, taking its **Item Versions** and every **Item Consumer** with it. A new path appeared, so a fresh **Catalog Item** is created at version 1. Anyone who had enabled that **Skill** silently loses it, and there is nothing in the interface that would tell them why. This is acceptable while the feature is dark and one person is using it. It is not acceptable once the `ai_catalog_skills` flag widens beyond that. It also diverges from the design document, which specifies a front matter `id` precisely so that "file renames and moves are safe as an item's `id` survives file reorganization". The proof of concept went with the directory name because the Agent Skills specification already requires the front matter `name` to equal the parent directory name, which makes the directory name a per-project identifier for free. That reasoning holds; it just does not survive a rename. This issue has no milestone. It is a follow-up, deliberately outside the current milestone's scope, recorded here so the divergence is tracked somewhere other than a glossary entry and a merge request comment. This needs a design decision before it needs code. Where the stable identifier lives determines everything else on the list below, and the two obvious options trade off against each other rather than one being clearly right. Front matter carries the identifier with the file, so it survives a move out of the box and works for a **Skill** that is copied between projects. But it is author-editable, it can collide, and the Agent Skills specification has no `id` field — so adding one means going beyond the vendored JSON schema, with the constraints ADR 0002 describes. An `internal_id` column on `ai_catalog_items` is authoritative and can carry a unique constraint, but it gives the reconcile step nothing to match on: it still has to work out which repository file corresponds to which existing record, which is the original problem. ## 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 - Depends on: https://gitlab.com/gitlab-org/gitlab/-/work_items/630878 - Agent Skills specification: https://agentskills.io/specification Read the proof of concept merge request to see the whole thing end to end. The domain glossary (`CONTEXT.md`) and the two architecture decision records (`docs/adr/`) live on that branch and are not on `master`. `CONTEXT.md` records this divergence under its flagged ambiguities, and ADR 0002 covers what vendoring the specification means for adding fields the specification does not define. ## Non-functional requirements - [ ] Documentation: an architecture decision record for whichever option is chosen, since this reverses a decision already recorded. - [ ] Feature flag: Not required. This changes how an existing gated feature reconciles, not what is reachable. - [ ] Performance: the reconcile step runs once per **Publish**; whatever replaces the path key must stay a single indexed lookup. - [ ] Testing: rename, move, copy-into-another-project and backfill cases, plus the existing drift case. ## Implementation plan Investigation and decisions first. Do not start with the migration. - [ ] ~backend Decide where the stable **Internal ID** lives: front matter, an `internal_id` column on `ai_catalog_items`, or both. Write up the trade-off — author-editable and collidable versus authoritative but needing a separate matching rule — and the cost of going beyond the vendored schema if front matter wins. - [ ] ~backend Decide what a rename does to **Item Versions**: mints a new **Item Version**, or only updates the **Definition**'s `path` on the existing one. The second keeps version history meaningful; the first makes the pointer immutable, which is what an **Item Version** is supposed to be. - [ ] ~backend Decide what happens when the identifier is missing, for a **Skill** authored before the change or by a tool that does not know about it. Falling back to the path preserves today's behaviour; refusing to publish does not. - [ ] ~backend Work out how reconcile matches a repository file to an existing **Catalog Item** under the chosen option, and rework `PublishService#existing_by_path` accordingly. - [ ] ~backend Decide what a collision means and where it surfaces: a **Rejection** from the **Validator**, a **Publish** failure, or a uniqueness violation. - [ ] ~backend Handle the existing drift case, where more than one **Catalog Item** maps to a single path. Today `flag_drift` logs it and the shadowed rows are dropped. A unique constraint on a stable identifier would make it impossible, but the existing rows still have to go somewhere. - [ ] ~backend Plan the backfill for **Catalog Items** created before the change, including what happens to any that cannot be matched. - [ ] ~backend Only then: migration, reconcile change, backfill, specs.