addyosmani / addyosmani/agent-skills

Version metadata disagrees across five manifests, so update checks cannot tell if a plugin is current

Aberta
#440 2 comentários 0 reações 0 responsáveis Ver no GitHub
Linguagem predominante
JavaScript
Estrelas
93.8k
Forks
10k
Merge médio
3d 15h
PRs com merge (30d)
23

Descrição

## Summary

Five manifests in this repo carry three different answers to "what version is this?", and none of them matches the actual release. The result is that neither Claude Code nor Codex can determine whether an installed copy is current.

Verified against `main` on 2026-07-31.

| Source | `version` | Consumed by |
|---|---|---|
| git tags / GitHub releases | **0.6.5** (2026-07-26) | humans |
| `plugin.json` | **1.0.0** | Codex |
| `.codex-plugin/plugin.json` | **1.0.0** | Codex |
| `.claude-plugin/plugin.json` | *absent* | — |
| `.claude-plugin/marketplace.json` (plugin entry) | *absent* | Claude Code |
| `.agents/plugins/marketplace.json` (plugin entry) | *absent* | Codex marketplace |

## Three consequences

**1. `1.0.0` has never changed, so Codex update checks no-op forever.**

It was introduced on 2026-06-10 and has not moved since, across 4 releases (0.6.2 → 0.6.5) and 100+ commits to `main`. A Codex client compares its cached `1.0.0` against the manifest's `1.0.0`, finds no delta, and reports success without updating. Silent staleness is the worst failure mode for an update check, because nothing surfaces it — the machine looks healthy while running June code.

**2. `1.0.0` is higher than the newest real release, `0.6.5`.**

Any tool that does resolve a manifest version concludes the local install is *ahead* of upstream. Correct semver comparison, wrong answer, and there is no version discipline to fall back on.

**3. The Claude marketplace entry has no `version`, so consumers fall back to keying by commit SHA.**

On my machine that produced two cache directories:

```
~/.claude/plugins/cache/addy-agent-skills/agent-skills/98967c45a42b/ (PR #396, 2026-07-12)
~/.claude/plugins/cache/addy-agent-skills/agent-skills/0300ca444c8c/ (PR #300, 2026-06-20)
```

A SHA is not orderable, so "is this current?" stops being a version comparison and becomes a git-history question: does any commit between the installed SHA and HEAD touch the plugin's files? That is answerable, but only against a repository with enough history to contain the installed SHA. Marketplace clones are commonly shallow, and there the query fails outright rather than returning an answer.

That is the practical cost of the absent field: with a version, "current?" is a string comparison any consumer can do. Without one, every consumer has to reimplement history-walking, and each gets to fail differently.

## Suggested fix

Make the git tag the single source of truth and carry it identically in all four plugin/marketplace manifests, bumped in the same commit that cuts a release:

- `plugin.json`
- `.codex-plugin/plugin.json`
- `.claude-plugin/marketplace.json` (the `plugins[].version` entry)
- `.agents/plugins/marketplace.json` (the `plugins[].version` entry)

`.claude-plugin/plugin.json` should either carry it too or be removed if it is vestigial.

The two `1.0.0` values need reconciling with `0.6.5`. Correcting them down is cleanest; if moving backwards is unacceptable, tagging the next release above `1.0.0` works equally well. Either is fine — the requirement is that the files agree.

A CI check that asserts all manifest versions equal the tag would keep them from drifting apart again.

## Why it matters beyond this repo

Both Claude Code and Codex install plugins from many marketplaces at once. A plugin whose version never changes is indistinguishable from one that is genuinely up to date, so users silently run stale skills, and the failure surfaces only as skills behaving differently than the documentation says they should.

Happy to open a PR if the direction is agreeable.

Guia de contribuição

Abrir o guia de contribuição

Avaliação

Esta issue ainda não foi avaliada.

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.