Getting Started

Install SkillSign, sign your first skill, and verify it — all in under a minute.

Prerequisites

GitHub Account
SkillSign uses GitHub OIDC for identity. You'll authenticate via your browser (or GitHub Actions OIDC in CI).
Python 3.14+
SkillSign is a Python CLI tool. You need Python 3.14 or later installed.
A SKILL.md file
The file you want to sign. Any valid SKILL.md file works — SkillSign handles normalization automatically.

Install

SkillSign requires Python 3.14+ and UV. Clone the repo and sync dependencies.

$ git clone https://github.com/bruk-io/skillsign.git \ && cd skillsign \ && uv sync

Verify the installation:

$ uv run skillsign --version skillsign 0.1.0

pip install, uvx, and brew distribution coming in Phase 3.

Sign your first skill

1

Create a manifest

Create a skillsign.yaml in the same directory as your SKILL.md:

skill_id: github.com/your-org/your-skill skill_version: 1.0.0
2

Authenticate with GitHub

This opens your browser for GitHub OIDC authentication:

$ uv run skillsign auth login Opening browser for GitHub authentication... ✓ Authenticated as github.com/your-username
3

Sign the skill

Sign your SKILL.md file. SkillSign reads the manifest, computes the canonical form, obtains a certificate, signs, and records in Rekor:

$ uv run skillsign sign ./SKILL.md ✓ Signed by: github.com/your-username ✓ Skill: github.com/your-org/your-skill@1.0.0 ✓ Certificate issued: 2026-03-03T10:00:00Z (expires 2026-03-03T10:10:00Z) ✓ Rekor log entry: https://rekor.sigstore.dev/api/v1/log/entries/24296fb2... ✓ Signature written to: SKILL.md.skillsign
✓

Done!

You now have a SKILL.md.skillsign sidecar file. Distribute it alongside your SKILL.md — consumers can verify your authorship.

Verify a skill

1

Basic verification

Verify a skill file and its sidecar:

$ uv run skillsign verify ./SKILL.md ✓ Sidecar parsed (version: 1) ✓ Digest verified (sha256:e3b0c4...) ✓ Signature valid (ECDSA P-256) ✓ Certificate chain verified ✓ Identity: https://github.com/your-username ✓ Rekor entry confirmed VERIFIED — signed by github.com/your-username
2

Strict mode (optional)

For higher assurance, use --strict to require live Rekor confirmation:

$ uv run skillsign verify --strict ./SKILL.md
3

With trust policy (optional)

Enforce organizational trust rules:

$ uv run skillsign verify --policy .skillsign-policy.yaml ./SKILL.md

Policy files can restrict which signers, organizations, and signature ages are acceptable.

CI Integration

SkillSign uses specific exit codes for easy CI pipeline integration.

Exit Code Meaning CI Action
0 VERIFIED Proceed — skill is trusted
1 Hard failure (TAMPERED, INVALID_CERT, etc.) Block — do not execute
2 UNSIGNED Decide based on policy
3 POLICY_FAIL Block — doesn't meet trust policy
10 CLI error Investigate — bad input or config

GitHub Actions example

- name: Verify skill signatures run: | pip install uv uv run skillsign verify \ --policy .skillsign-policy.yaml \ ./skills/**/*.md

Next steps

Dive deeper into the specification, explore the architecture, or read the full documentation.

How It Works Source Code