Versioning and ownership
Versions
Section titled “Versions”Semver is required
Section titled “Semver is required”Every skill version must follow semantic versioning: MAJOR.MINOR.PATCH. The server rejects versions that don’t match this format.
Examples of valid versions: 1.0.0, 2.3.1, 0.1.0
Examples of invalid versions: v1.0.0, 1.0, latest, 2024-01-15
Versions are immutable
Section titled “Versions are immutable”Once a version is published, its content cannot be changed. The primary key constraint on (skill_name, version) enforces this at the database level. If you publish my-skill@1.0.0, that content is fixed. To update the skill, publish 1.0.1 or 1.1.0.
Immutability means installs are reproducible. If you pin a version and record its SHA-256 digest, you can verify the content has not changed:
skillsctl install my-skill@1.0.0 --digest sha256:abc123...latest_version tracking
Section titled “latest_version tracking”The registry tracks a latest_version field for each skill. When a new version is published, latest_version is updated only if the new version is semver-greater than the current latest. Publishing an old version (e.g., a backport to 1.x while 2.0.0 is current) does not change latest_version.
skillsctl install my-skill without a version specifier installs latest_version.
Changelogs
Section titled “Changelogs”Each version can include a changelog message. Pass it with --changelog when publishing:
skillsctl publish \ --name my-skill \ --version 1.1.0 \ --description "..." \ --file my-skill.md \ --changelog "add output format instructions, fix typo in section 2"Changelogs are stored with each version and help users decide whether to update.
Digest verification
Section titled “Digest verification”Every version has a SHA-256 digest computed from its content. The digest is displayed when you publish:
Published my-skill@1.0.0 (sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855)Pin a version with its digest to detect if the content has been tampered with:
skillsctl install my-skill@1.0.0 --digest sha256:e3b0c44...If the digest does not match, installation fails.
Ownership
Section titled “Ownership”Keyed on OIDC subject
Section titled “Keyed on OIDC subject”Skill ownership is tied to the OIDC subject (sub claim) of the user who first published the skill. The subject is an opaque identifier assigned by the OIDC provider - it does not change when the user updates their email or display name.
Using subject instead of email means:
- A user who changes their email retains ownership of their skills
- Ownership is stable across provider-side profile updates
- Two accounts at the same provider always have different subjects
What ownership enforces
Section titled “What ownership enforces”Once a skill is owned by a subject, only that subject can publish new versions of it. Other users receive an error if they attempt to publish to a skill name they don’t own.
Ownership is established on first publish. There is no separate ownership claim step.
Admin override
Section titled “Admin override”Admin users (members of the group specified by OIDC_ADMIN_GROUP) can publish to any skill regardless of ownership. This allows platform admins to take over unmaintained skills or handle off-boarding.
Transferring ownership
Section titled “Transferring ownership”Ownership transfer is not currently supported through the CLI. An admin can update the owner field directly in the database if needed.
Next steps
Section titled “Next steps”- Auth model - how OIDC subjects are established
- Security - how immutability and digests fit into the security model