skillsign

# skillsign

Cryptographic signing and verification for agent skill folders using ed25519 keys. Protects your skills from tampering and lets you verify who wrote them.

## Install

```bash
pip3 install cryptography
```

That's the only dependency. The tool is a single Python file.

## Commands

### Generate a signing identity
```bash
python3 skillsign.py keygen
python3 skillsign.py keygen --name myagent
```
Creates an ed25519 keypair in `~/.skillsign/keys/`. Share the `.pub` file. Keep the `.pem` file secret.

### Sign a skill folder
```bash
python3 skillsign.py sign ./my-skill/
python3 skillsign.py sign ./my-skill/ --key ~/.skillsign/keys/myagent.pem
```
Hashes every file (SHA-256), builds a manifest, signs it with your private key. Creates `.skillsig/` inside the folder.

### Verify a skill folder
```bash
python3 skillsign.py verify ./my-skill/
```
Detects modified, added, or removed files. Verifies the cryptographic signature. Shows whether the signer is trusted.

### Inspect signature metadata
```bash
python3 skillsign.py inspect ./my-skill/
```
Shows signer fingerprint, timestamp, file count, and all covered files with their hashes.

### Trust an author
```bash
python3 skillsign.py trust ./their-key.pub
```
Adds a public key to your local trusted authors list.

### List trusted authors
```bash
python3 skillsign.py trusted
```

### View provenance chain (isnād)
```bash
python3 skillsign.py chain ./my-skill/
```
Shows the full signing history — every author who signed the folder, in order.

## When to Use

- **After installing a new skill** — verify it hasn't been tampered with
- **Before running untrusted code** — check who signed it and whether you trust them
- **Periodically** — re-verify your skill folders to detect unauthorized modifications
- **When publishing skills** — sign your work so others can verify it came from you
- **When auditing your agent's integrity** — run verify on all your skill folders

## Example Workflow

```bash
# First time: create you...

# skillsign 🛡️

Cryptographic signing and verification for agent skill folders using ed25519 keys.

Inspired by the Islamic concept of **isnād** — a chain of narration where each link must be verifiable. If any link is broken or untrusted, the whole chain is suspect.

## Why

AI agents install skills from shared registries. But there's no way to verify:
- **Who wrote a skill** — Is this really from the author it claims?
- **Has it been modified** — Did someone inject malicious code after publishing?
- **Do I trust this author** — Should my agent run this code?

`skillsign` answers all three. It creates a cryptographic chain of trust for agent skills.

## Install

**Requirements:** Python 3.8+

```bash
pip install cryptography
```

Or install as a package:

```bash
pip install .
```

## Quick Start

```bash
# 1. Generate your signing identity
python3 skillsign.py keygen

# 2. Sign a skill folder
python3 skillsign.py sign ./my-skill/

# 3. Verify it later
python3 skillsign.py verify ./my-skill/
```

## Commands

### `keygen` — Generate a signing identity

```bash
python3 skillsign.py keygen
python3 skillsign.py keygen --name alice
```

Creates an ed25519 keypair in `~/.skillsign/keys/`. The private key is set to `0600` permissions. Share the `.pub` file with others. Keep the `.pem` file secret.

**Output:**
```
Keypair generated:
  Private: ~/.skillsign/keys/alice.pem
  Public:  ~/.skillsign/keys/alice.pub
  Fingerprint: f69159d8a25e8e32
```

### `sign` — Sign a skill folder

```bash
python3 skillsign.py sign ./my-skill/
python3 skillsign.py sign ./my-skill/ --key ~/.skillsign/keys/alice.pem
```

Hashes every file in the folder (SHA-256), builds a sorted manifest, and signs it with your ed25519 private key. Creates a `.skillsig/` directory inside the folder.

**Output:**
```
✅ Signed 14 files in my-skill/
   Signer: f69159d8a25e8e32
   Signature: ./my-skill/.skillsig/signature.bin
```

### `verify` — Verify a skill folder

```bash
python3 skillsign.py verify ./my-ski...