How It Works

SkillSign uses Sigstore keyless signing to bind your GitHub identity to your SKILL.md files without managing long-lived private keys.

Important: Signing is not authorization

Today, anyone can create a skill_id and sign it with their own identity. Verification confirms who signed a skill and that the content hasn't been tampered with — but it does not confirm that the signer is trustworthy.

A future skill registry will bind skill_id ownership to specific signers, closing this gap. Until then, consumers should verify the signer's identity matches who they expect, not just that a valid signature exists.

Signing Flow

The signing protocol produces a detached sidecar file containing the signature, certificate, and transparency log entry. The SKILL.md file is never modified.

Signing Modes

SkillSign supports two signing paths with different identity and trust properties.

CI Signing (GitHub Actions)

In GitHub Actions, SkillSign uses ambient OIDC credentials — no browser login needed. The Fulcio certificate SAN encodes the full workflow path:

https://github.com/{org}/{repo}/.github/workflows/{workflow}.yml@refs/heads/{branch}

This ties the signature to a repository and workflow, not a person. Anyone with write access can trigger the workflow and produce a valid signature. The trust boundary is the repo's access controls.

Developer Signing (Interactive)

When a developer runs skillsign sign locally, they authenticate via browser-based OIDC. The certificate SAN encodes their personal identity:

GitHub OAuth: https://github.com/{username} Email OAuth: user@example.com

This ties the signature to an individual. Only someone who can authenticate as that GitHub user can produce the signature. The trust boundary is the person's account security.

Why signing alone isn't enough

Today, signing proves identity but not authorization. Anyone can sign any skill_id. A future registry will enforce who is allowed to sign what.

CI signatures prove "this repo produced this artifact" — but repos change hands, maintainers rotate, and workflow files can be modified by anyone with push access. A compromised repo produces legitimate-looking CI signatures.

Developer signatures prove "this person endorsed this artifact." Combined with a future registry that maps skill_id to authorized signers, this enables a stronger trust model:

  1. A registry entry says "skill github.com/acme/deploy may only be signed by https://github.com/alice"
  2. Even if the repo is compromised, an attacker can't produce a signature that matches the registry's authorized signer
  3. Consumers verify both the signature and the signer-to-skill binding from the registry

CI signing is convenient for automation. Developer signing is stronger for trust — especially once a registry exists to enforce who is allowed to sign what.

Verification Flow

Verification checks the signature, certificate chain, signer identity, and optionally enforces a trust policy. Each failure produces a specific result code.

Verification Results

Every verification attempt produces one of these results, each with a specific exit code for CI integration.

Remember: a VERIFIED result confirms the signature is valid and the signer's identity — but until a registry exists, it's up to you to confirm the signer is someone you trust for that particular skill.

Exit 0 VERIFIED Signature valid, signer identity confirmed, content unmodified. Exit 1 TAMPERED Digest mismatch — the file has been modified after signing. Exit 1 INVALID_CERT Certificate cannot be verified against the Fulcio root. Exit 1 IDENTITY_MISMATCH Certificate SAN does not match the claimed signer. Exit 2 UNSIGNED No sidecar file found. Not a hard failure by default. Exit 3 POLICY_FAIL Signature is valid but does not meet the caller's trust policy. Exit 1 SKILL_ID_MISMATCH Skill_id owner path doesn't match signer owner path. Exit 1 MALFORMED_SIDECAR Sidecar file is present but cannot be parsed or has invalid structure.