Software Capability Sharing Protocol
Package any improvement to any open-source software. Share it. Let anyone install it in one command.
改 → 打包 → 分享 → 一键装
A user can ask an AI agent to add TOTP 2FA to their app in ten minutes. But sharing that improvement with a thousand other users of the same software still requires a pull request, a code review, and a maintainer who has time — a process measured in months, not seconds.
User knowledge evaporates. Every user rediscovers the same improvements, forever.
SCSP is a language-agnostic protocol for packaging, distributing, and installing software improvements as .scsp capability packages.
A .scsp file describes intent, not code. It specifies what an improvement does, where it connects to the host application, what constraints it must never violate, and how to roll it back. Any AI agent that understands SCSP can read a capability package and adapt it to any compatible codebase — regardless of language, framework, or version.
Developer declares extension points ──▶ scsp-manifest.yaml
User builds a local improvement ──▶ scsp pack ──▶ my-feature.scsp
User publishes to the community ──▶ scsp publish
Anyone installs in one command ──▶ scsp install auth-totp-v1
npm install -g @yytyyf/scspThen install the Claude Code skills so you can run installs from inside any session:
scsp skills install --globalAvailable skills: /scsp-onboard · /scsp-install · /scsp-explore · /scsp-sync · /scsp-review · /scsp-health
This is what installing a community TOTP two-factor authentication capability looks like:
$ scsp install auth-totp-v1
Fetching auth-totp-v1... ✓ signature verified (alice · ed25519)
[1/6] PROBE — scanning extension points
✓ Entity: User (id, email)
✓ Hook: auth.password_login.post_verify → src/routes/auth/login.ts:47
⚠ Slot: settings.security not found
→ totp-settings-ui will be skipped
→ backend enforcement still installs
[2/6] VALIDATE
✓ surfaces, anchors, permissions — all clear
✓ no conflicts with installed capabilities
[3/6] DRY-RUN
+ src/middleware/totp.ts
+ src/routes/auth/2fa.ts
+ migrations/20260419_add_totp.sql
~ src/routes/auth/login.ts (+12 / -2)
~ src/models/user.ts (+3 / -0)
[4/6] CONFIRM
Apply these changes? [y/N]: y
[5/6] APPLY
✓ files written · migration applied · otplib@12.0.1 installed
[6/6] VERIFY
✓ contract-enable-2fa
✓ contract-totp-verify-success
✓ contract-lockout-after-5-failures
✓ contract-recovery-code-single-use
✓ auth-totp-v1 v1.0.0 installed · rollback: scsp rollback auth-totp-v1
No forking. No migration docs. No reading someone else's codebase.
Every scsp install runs the same safe, reversible pipeline:
| Stage | Name | What happens |
|---|---|---|
| 1 | PROBE | Agent scans for declared extension points. Confirms requirements are met. |
| 2 | VALIDATE | Cross-checks capability against the host manifest. Detects conflicts. |
| 3 | DRY-RUN | Generates all changes. Produces a full diff. Nothing is written yet. |
| 4 | CONFIRM | Human gate. You review and approve. |
| 5 | APPLY | Files written, migrations run, dependencies installed, snapshot saved. |
| 6 | VERIFY | Runs declared contracts against the live system. On failure: auto-rollback. |
| Artifact | Who writes it | What it does |
|---|---|---|
scsp-manifest.yaml |
App developer | Declares available surfaces, hooks, and slots |
host-snapshot.json |
Executor agent | Maps manifest declarations to concrete file locations |
my-feature.scsp |
Community user | Describes an improvement in the manifest's vocabulary |
This separation is what makes capabilities language-agnostic: they reference abstract surfaces like auth and User, not specific files like src/models/user.ts.
SCSP ships as a set of Claude Code skills — the executor runs directly in your coding session, with full codebase context and no separate API key needed.
scsp skills install --global # available in every session
scsp skills install # project-only/scsp-onboard — Initialize SCSP for a project
Deep-reads your codebase and generates a scsp-manifest.yaml and host-snapshot.json with real anchor locations. Asks clarifying questions only when the code is ambiguous. Replaces the scsp init command (which uses shallow file scanning).
/scsp-onboard
/scsp-install — Install a capability package
Full six-stage pipeline running in your Claude Code session. Understands your exact codebase at the time of installation — not a snapshot from when the package was written.
/scsp-install auth-totp-v1
/scsp-install auth-totp-v1 --dry-run
/scsp-install ./my-local-capability.scsp
/scsp-explore — Browse the registry with AI recommendations
Reads your manifest and recommends capabilities that fit your actual codebase — not just tag matches. Explains why each capability is (or isn't) a good fit.
/scsp-explore
/scsp-explore auth
/scsp-sync — Sync manifest after refactors
Detects drifted anchor locations, new extension points, and signature changes. Updates host-snapshot.json to match the current codebase.
/scsp-sync
/scsp-health — Check installed capabilities
Re-runs all probes for installed capabilities. Identifies which ones have degraded or broken due to recent code changes.
/scsp-health
/scsp-health auth-totp-v1
/scsp-health --contracts
/scsp-review — Peer-review a capability package
Validates probes, blast radius, NCV coverage, and contract completeness before publishing.
/scsp-review ./my-feature.scsp
Add a capability browser to any project's docs site in one line:
<script src="https://unpkg.com/@yytyyf/scsp/community-sdk/widget.js"></script>
<scsp-community
registry="https://raw.githubusercontent.com/IvyYang1999/scsp/main/registry/index.json"
theme="auto"
max-height="600px"
></scsp-community>The <scsp-community> web component is a self-contained Shadow DOM widget — no external CSS, no framework dependencies, light/dark/auto theme support. Drop it into any HTML page.
Live example: Swob Community — the Claude Code session manager uses SCSP to let users install capabilities like AI Session Summarizer.
Add a scsp-manifest.yaml to your repo root. That's it — your project now has a stable extension contract that AI agents and community users can build against, without you writing a single plugin API.
# scsp-manifest.yaml
scsp_manifest: "0.1"
name: my-app
version: "1.0.0"
repo: https://github.com/you/my-app
surfaces:
entities: [User]
logic_domains: [auth]
ui_areas: [settings]
anchors:
hooks:
- id: auth.password_login.post_verify
description: "Fires after password verification, before session creation"
slots:
- id: settings.security
description: "Security settings panel injection point"Or generate it automatically with:
# In your project, inside a Claude Code session:
/scsp-onboardA .scsp file is a structured document: YAML frontmatter followed by fenced YAML sections.
---
scsp: "0.1"
id: auth-totp-v1
name: "TOTP Two-Factor Authentication"
version: "1.0.0"
tags: ["auth", "security", "2fa"]
author:
name: alice
key: "ed25519:MCowBQYDK2VwAyEA4k7..."
signature: "ed25519:3d9f2a1b..."
env_hint:
runtime: ["node>=18", "python>=3.10", "go>=1.21"]
frameworks: [express, fastapi, gin, nextjs]
requires:
surfaces:
entities: [User]
logic_domains: [auth]
anchors:
hooks: [auth.password_login.post_verify]
components:
- id: totp-backend
layer: module
optional: false
blast_radius:
structural_impact: [Route, Middleware, DatabaseSchema]
rollback:
stateful:
- type: schema_migration
down: |
ALTER TABLE users DROP COLUMN IF EXISTS totp_secret;
DROP TABLE IF EXISTS recovery_codes;
---
## Intent
TOTP Two-Factor Authentication adds RFC 6238-compliant time-based one-time
password support to the host application's login flow...The body continues with fenced probes:, ncv:, contracts:, fixtures:, and interfaces: sections.
Section reference
| Section | Purpose |
|---|---|
| Frontmatter | Identity, author, signature, environment hints, required surfaces and anchors, component declarations, conflict graph |
probes: |
Checks run against the codebase before touching anything. on_fail: abort stops installation; on_fail: warn skips optional components |
ncv: |
Negative Constraint Verification — things the implementation must never do (log secrets, bypass auth, etc.) |
contracts: |
Behavioral specifications as given/when/then. Run during VERIFY stage against the live system |
fixtures: |
Test data needed to run contracts |
interfaces: |
Public API surface the capability exposes, with request/response schemas |
The reference registry lives at IvyYang1999/scsp. Currently includes:
| Capability | Type | Description |
|---|---|---|
auth-totp-v1 |
Module | TOTP 2FA with schema migration, brute-force lockout, single-use recovery codes, OWASP ASVS 2.8 compliance |
approval-workflow-v1 |
Behavior | Multi-step approval state machine with audit trail and notifications |
calendar-week-view-v1 |
Component | 7-day week view with drag-and-drop event rescheduling |
perf-image-lazy-load-v1 |
Improvement | IntersectionObserver lazy loading, zero dependencies |
swob-session-summarizer-v1 |
Module | AI-generated session summaries for Swob |
# From inside a Claude Code session (recommended):
/scsp-review ./my-feature.scsp # validate before submitting
# Then open a PR to add your capability under:
# registry/capabilities/<your-id>/A GitHub Actions workflow validates every PR against the JSON Schema before merge.
scsp/
├── src/
│ ├── cli.ts # scsp CLI (validate, inspect, pack, publish, skills)
│ └── skills.ts # skills install/list/uninstall
│
├── skills/ # Claude Code skill files (.md)
│ ├── scsp-onboard.md
│ ├── scsp-install.md
│ ├── scsp-explore.md
│ ├── scsp-sync.md
│ ├── scsp-health.md
│ └── scsp-review.md
│
├── registry/ # Reference capability registry
│ ├── index.json
│ └── capabilities/
│ └── auth-totp-v1/
│ ├── auth-totp-v1.scsp
│ └── metadata.json
│
├── community-sdk/ # Embeddable web component
│ ├── widget.js # <scsp-community> custom element
│ ├── index.html # Standalone community page
│ └── styles.css
│
├── spec/ # JSON Schemas
│ ├── scsp-capability.schema.json
│ ├── scsp-manifest.schema.json
│ └── scsp-host-snapshot.schema.json
│
├── docs/
│ ├── PROTOCOL.md # Full protocol spec (21 sections)
│ └── REGISTRY-API.draft.md # HTTP registry API (V0.3 planned)
│
└── examples/
├── capabilities/ # Full example .scsp files
└── manifests/ # Example host manifests
V0.1 — Protocol Foundation ✓
- Complete protocol specification (21 sections)
-
.scspfile format with YAML frontmatter + fenced sections - JSON Schema for capability packages, manifests, and snapshots
- CLI:
validate,inspect,pack,publish,install,skills - 5 production-quality example capability packages
- Git-based registry protocol
- 6-stage execution model
- Negative Constraint Verification (NCV)
- Conflict graph and blast radius declarations
V0.2 — Skills & Community SDK ✓ (current)
- 6 Claude Code skills (
/scsp-onboard,/scsp-install,/scsp-explore,/scsp-sync,/scsp-health,/scsp-review) -
<scsp-community>embeddable web component - Standalone community page with dark/light theme
- Real-world integration: Swob +
swob-session-summarizer-v1
V0.3 — HTTP Registry & Executor
- HTTP Registry API (
POST /v1/capabilities,GET /v1/capabilities/:id, search by tag) - Full executor agent integration (Claude / local models)
- Automatic probe execution against live codebases
-
scsp rollback <id>with automatic migration reversal - Capability dependency resolution
- Signed install receipts
V0.4 — Ecosystem
- Capability lineage graph: trace evolution across forks and adaptations
- Capability composition: install multiple capabilities as a bundle
-
scsp audit: security review of installed capabilities - Micropayment model: authors earn per install
git clone https://github.com/IvyYang1999/scsp
cd scsp
npm install
npm test # validate all example capabilities
npm run build # compile TypeScriptThe bottleneck is no longer implementation — it is distribution.
AI agents can write production-quality code from a description. A user can add TOTP 2FA to their app in ten minutes. But that improvement dies on their machine. It never reaches the next user who wants the same thing.
SCSP is the missing layer: a protocol that lets the agent's output become a portable, shareable, installable artifact. The .scsp file is to software improvements what .deb is to software itself — a standardized container that any compatible system can consume.
MIT — see LICENSE
Built at a hackathon. Designed for the long run.