The Skill Lifecycle

SkillGem manages the complete lifecycle of agent skills — from initial creation through monetization, reputation building, and eventual sunset. This page maps every stage.

Claim/Import → Create → Sign/Attest → Version → Publish ↓ Deprecate ← Improve ← Feedback ← Use ← Pay ← Discover ↑ ↓ └──────────── Compose & Chain ←────────────────┘

Stage 0: Claim & Import

Authors may already have skills published on GitHub, ClawHub, Skild, or npm. SkillGem lets you claim ownership and import existing work — no need to start from scratch.

How it works

  • GitHub import — Point to a repo with SKILL.md. Verify ownership via GitHub OAuth or a .skillgem file in the repo. Metadata is imported and a SkillGem listing is created.
  • Marketplace import — Link existing ClawHub, Skild, or npm listings. Cross-reference author identity.
  • Claim verification — Prove authorship by signing with your ERC-8004 on-chain identity. The signature is recorded on-chain, establishing provenance.
  • Sync — Optionally keep the listing synced with the source repo. Updates trigger new versions automatically.

Stage 1: Create

Two paths to skill creation:

AI-Assisted (Skill Builder)

The Skill Builder interviews you about your domain expertise and produces a structured SKILL.md. No coding required. It extracts procedures, decision trees, edge cases, and best practices.

Manual / Developer Path

  • Write SKILL.md directly following the Agent Skills spec
  • Import from an existing GitHub repo (Stage 0)
  • Fork and customize an existing skill (attribution chain preserved)

Stage 2: Sign & Attest

Every skill gets a provenance chain inspired by SLSA (Supply chain Levels for Software Artifacts):

  • Author signature — Cryptographic signature tied to your ERC-8004 identity. Proves who created the skill and when.
  • Content hash — SHA-256 of the complete skill directory. Any change invalidates the hash — tamper-evident.
  • Build attestation — If AI-assisted, records builder version, session ID, model used. Transparency about how the skill was created.
  • Dependency attestation — Records references to other skills or external tools (MCP servers, APIs) and their versions.

The signature + attestation bundle is verified by the gateway on every access.

Stage 3: Version & Package

  • Semantic versioning — MAJOR (breaking changes), MINOR (new capabilities), PATCH (fixes)
  • Changelog — Required for every version bump. Can be AI-generated from diff.
  • Immutable versions — Once published, a version cannot be modified — only deprecated.
  • Pre-release channels — 1.2.0-beta.1 for testing before stable release.
  • Dependency pinning — Skills declare version ranges for dependencies.

Stage 4: Publish

Dual-track publishing to the hybrid architecture:

Registry (discovery + free skills)

Metadata indexed for search: name, description, author, versions, tags, price. Full content available for free/open skills. Content hash verified on publish.

Gateway (serving + paid skills)

Skill content served via HTTP on demand. x402 payment gating for premium skills. Author sets price per access. Content delivered with signature verification headers.

Security on publish

  • Automated content scanning (malware, prompt injection patterns)
  • Community reporting with auto-hide at 3+ unique reports
  • Verified author badges tied to ERC-8004 identity
  • First-time author review queue

Stage 5: Discover

  • Semantic search — Agents describe what they need; registry returns skills ranked by relevance and reputation
  • Reputation-weighted ranking — ERC-8004 scores factor into discovery. Higher reputation = more visible.
  • Compatibility filtering — Filter by platform (Claude Code, Cursor, etc.) and requirements
  • Recommendations — "Skills used together" and "Authors who build X also build Y"
  • Agent-to-agent discovery — Agents recommend skills to each other via A2A protocol

Stage 6: Access & Pay

The Skill Gateway serves skills on demand:

Agent  →  GET /skills/medical-triage@^1.0
Gateway →  402 Payment Required (x402 details)
Agent  →  Pays via stablecoin
Agent  →  GET /skills/medical-triage@^1.0 (with payment proof)
Gateway →  200 OK (SKILL.md content + signature headers)

Access models:

  • Per-use — Pay each time the agent loads the skill
  • Cached access — After paying, cache locally for a TTL (e.g., 24 hours)
  • Subscription — Time-based access for frequent users
  • Team/org licenses — Pay once for all agents in an organization

Stage 7: Use & Execute

  • Progressive disclosure — Name + description at discovery, full SKILL.md on activation, scripts/references on demand
  • Execution tracking — Gateway logs usage metadata (not task content) for analytics and reputation
  • Composition runtime — Skills load dependencies in sequence, sharing execution context
  • Sandboxing — Scripts execute in isolated environments. allowed-tools governs permissions.

Stage 8: Feedback & Reputation

Usage generates quality signals that feed the ERC-8004 reputation system:

  • Automatic signals — Task completion rate, deviation rate, execution duration
  • Agent feedback — Structured scores submitted to the Reputation Registry
  • Human feedback — End users rate skills from the marketplace
  • Third-party validation — Independent validators verify quality via the Validation Registry
  • Author response — Authors can respond to feedback, demonstrating engagement

Stage 9: Improve & Evolve

  • Analytics dashboard — Usage counts, success rates, feedback trends, revenue over time
  • AI-assisted improvement — Skill Builder analyzes feedback and suggests refinements
  • A/B versioning — Route traffic between stable and beta, compare metrics, promote when confident
  • Regression detection — Auto-alert if a new version performs worse than previous
  • Skill forking — Others can fork and improve skills with attribution chain preserved

Stage 10: Compose & Chain

Skills working together:

  • Dependency declaration — Skills declare dependencies on other skills in frontmatter
  • Skill pipelines — Meta-skills orchestrate multiple sub-skills in sequence
  • Shared context — Skills in a pipeline share execution context; output flows to next skill
  • Revenue splitting — x402 payments split across all contributing authors when composed skills are used

Stage 11: Deprecate & Sunset

  • Deprecation notice — Author marks skill as deprecated with migration path
  • Sunset period — Deprecated skills remain accessible for 90 days (configurable)
  • Agent notifications — Agents using deprecated skills are notified to upgrade
  • Archival — After sunset, content is archived. Historical reputation preserved in ERC-8004.

Stage 12: MCP Dependencies & Testing

Skills often depend on external tools via MCP (Model Context Protocol). These need explicit declaration and testing.

MCP Tool Declarations

Skills declare MCP server dependencies in frontmatter. The runtime checks availability and can auto-install missing servers (with user approval). Skills specify fallback behavior for unavailable tools.

Sandbox Testing

Skills are tested in an isolated sandbox before publishing:

my-skill/
├── SKILL.md
├── scripts/
├── tests/
│   ├── test-config.yaml      # Test scenarios
│   ├── mock-responses/       # Mock MCP tool responses
│   └── expected-outputs/     # Expected results
  • Author defines test scenarios with expected behavior
  • Sandbox provides mock MCP servers simulating tool responses
  • Tests must pass before publishing (enforced by registry)
  • Published skills are periodically re-tested against updated MCP versions

Next Steps

Start by understanding what skills are, then create your first skill with the AI-assisted Skill Builder.