diff --git a/moltrust/SKILL.md b/moltrust/SKILL.md
new file mode 100644
index 00000000..ed6d55d3
--- /dev/null
+++ b/moltrust/SKILL.md
@@ -0,0 +1,147 @@
+---
+name: moltrust
+description: >
+  Identity verification and reputation scoring for AI agent skills. Use when you need to verify
+  a skill publisher's identity, check their trust score, rate an agent after an interaction,
+  or issue/verify W3C Verifiable Credentials.
+  Built on W3C DID standards and Ed25519 cryptography to help open skill ecosystems establish
+  publisher trust on-chain and off-chain.
+
+metadata:
+  openclaw:
+    requires:
+      env:
+        - MOLTRUST_API_KEY
+      bins:
+        - curl
+    primaryEnv: MOLTRUST_API_KEY
+---
+
+# MolTrust — Publisher Verification for AI Agent Skills
+
+Verify skill publisher identity, check reputation scores, and issue cryptographic credentials. Designed for open skill ecosystems where publisher trust matters — whether your agents operate on traditional infrastructure or blockchain-native networks.
+
+## Why This Exists
+
+Open skill registries face a real challenge: how do you know who published a skill, and whether you should trust it? MolTrust provides the verification layer — every publisher gets a W3C Decentralized Identifier, reputation scores are tracked across interactions, and Ed25519-signed credentials offer cryptographic proof of identity. This is especially critical in crypto and DeFi contexts where autonomous agents manage wallets, sign transactions, and interact across trust boundaries.
+
+## Installation
+```bash
+pip install moltrust
+```
+
+## Setup
+
+Get your API key at https://moltrust.ch
+```bash
+export MOLTRUST_API_KEY="mt_your_key_here"
+```
+
+## Usage
+
+### Register as a Skill Publisher
+```python
+from moltrust import MolTrust
+
+mt = MolTrust()
+agent = mt.register("MySkillPublisher", platform="openclaw")
+print(agent.did)  # did:moltrust:...
+```
+
+Returns a `did:moltrust:...` identifier, verification status, and a W3C Verifiable Credential.
+
+### Verify a Skill Publisher
+```python
+is_verified = mt.verify("did:moltrust:a1b2c3d4e5f60718")
+```
+
+Returns verification status, display name, platform, trust score, and registration date.
+
+### Check Publisher Reputation
+```python
+rep = mt.get_reputation("did:moltrust:a1b2c3d4e5f60718")
+if rep.score >= 3.0 and rep.total_ratings >= 3:
+    print("Trusted publisher — safe to use skill")
+else:
+    print("New or unverified publisher — review before using")
+```
+
+Returns a 1–5 trust score and total number of ratings.
+
+### Rate an Agent
+After working with an agent, submit a rating to build the trust network.
+```python
+mt.rate(
+    from_did="did:moltrust:your_did",
+    to_did="did:moltrust:their_did",
+    score=5
+)
+```
+
+Score range: 1 (untrusted) to 5 (highly trusted).
+
+### Issue a Publisher Credential
+Create a tamper-proof W3C Verifiable Credential for an agent.
+```python
+vc = mt.issue_credential(
+    subject_did="did:moltrust:their_did",
+    credential_type="AgentTrustCredential"
+)
+```
+
+Returns an Ed25519-signed credential with issuer, subject, issuance date, and expiration.
+
+### Verify a Credential
+Check if a credential is authentic and unmodified.
+```python
+result = mt.verify_credential(vc)
+print(result.valid)  # True
+```
+
+Returns validity status, issuer, subject, type, and expiration check. The underlying API call is a POST with `{"credential": { ... }}`.
+
+### Pre-Install Trust Check
+A typical pattern before installing a skill from an unknown publisher:
+```python
+def check_publisher(publisher_did: str):
+    """Verify a skill publisher before installing their skill."""
+    if not mt.verify(publisher_did):
+        return {"trusted": False, "reason": "Publisher not found in registry"}
+    rep = mt.get_reputation(publisher_did)
+    if rep.score < 3.0:
+        return {"trusted": False, "reason": f"Low trust score: {rep.score}"}
+    return {"trusted": True, "score": rep.score, "ratings": rep.total_ratings}
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| W3C DID Identity | Every publisher gets a `did:moltrust` decentralized identifier |
+| Reputation Scoring | 1-5 star ratings aggregated across interactions |
+| Verifiable Credentials | Ed25519-signed W3C Verifiable Credentials |
+| A2A Agent Cards | Google A2A protocol compatible discovery |
+| Crypto-Native Trust | Ideal for DeFi agents, wallet signers, and cross-chain workflows |
+| Credit-Based API | 100 free credits on signup, pay-per-call pricing |
+
+## API Reference
+
+Base URL: `https://api.moltrust.ch`
+
+| Endpoint | Method | Auth | Description |
+|----------|--------|------|-------------|
+| `/identity/register` | POST | API key | Register a new agent DID |
+| `/identity/verify/{did}` | GET | — | Verify an agent's identity |
+| `/reputation/query/{did}` | GET | — | Get reputation score (1-5) |
+| `/reputation/rate` | POST | API key | Rate an agent (1-5 stars) |
+| `/credentials/issue` | POST | API key | Issue a Verifiable Credential |
+| `/credentials/verify` | POST | — | Verify a credential |
+| `/stats` | GET | — | Network statistics |
+
+## Links
+
+- Website: https://moltrust.ch
+- API Docs: https://api.moltrust.ch/docs
+- SDK: https://github.com/MoltyCel/moltrust-sdk
+- PyPI: https://pypi.org/project/moltrust/
+- MCP Server: `uvx moltrust-mcp-server` ([PyPI](https://pypi.org/project/moltrust-mcp-server/))
diff --git a/moltrust/references/api-docs.md b/moltrust/references/api-docs.md
new file mode 100644
index 00000000..ddd6a450
--- /dev/null
+++ b/moltrust/references/api-docs.md
@@ -0,0 +1,312 @@
+# MolTrust API Reference
+
+Base URL: `https://api.moltrust.ch`
+
+All authenticated requests require header: `X-API-Key: YOUR_KEY`
+
+---
+
+## Identity
+
+### Register an Agent
+
+```
+POST /identity/register
+```
+
+**Headers:** `X-API-Key` (required)
+
+**Body:**
+```json
+{
+  "display_name": "MySkillPublisher",
+  "platform": "openclaw"
+}
+```
+
+**Response:**
+```json
+{
+  "did": "did:moltrust:5d833cab8771467f",
+  "display_name": "MySkillPublisher",
+  "status": "registered",
+  "credential": { "...W3C Verifiable Credential..." },
+  "credits": {
+    "balance": 100,
+    "currency": "CREDITS"
+  }
+}
+```
+
+New publishers receive 100 free API credits on registration.
+
+### Verify an Agent
+
+```
+GET /identity/verify/{did}
+```
+
+**Response:**
+```json
+{
+  "did": "did:moltrust:5d833cab8771467f",
+  "verified": true,
+  "reputation": 4.2
+}
+```
+
+### Resolve a DID
+
+```
+GET /identity/resolve/{did}
+```
+
+**Response:**
+```json
+{
+  "@context": "https://www.w3.org/ns/did/v1",
+  "id": "did:moltrust:5d833cab8771467f",
+  "controller": "did:web:api.moltrust.ch",
+  "metadata": {
+    "display_name": "MySkillPublisher",
+    "platform": "openclaw",
+    "created": "2026-01-15T12:00:00",
+    "trust_provider": "MolTrust"
+  }
+}
+```
+
+---
+
+## Reputation
+
+### Query Reputation
+
+```
+GET /reputation/query/{did}
+```
+
+**Response:**
+```json
+{
+  "did": "did:moltrust:5d833cab8771467f",
+  "score": 4.2,
+  "total_ratings": 17
+}
+```
+
+### Rate an Agent
+
+```
+POST /reputation/rate
+```
+
+**Headers:** `X-API-Key` (required)
+
+**Body:**
+```json
+{
+  "from_did": "did:moltrust:my_did",
+  "to_did": "did:moltrust:their_did",
+  "score": 5
+}
+```
+
+**Constraints:**
+- Score: 1-5 (integer)
+- Cannot rate yourself
+
+**Response:**
+```json
+{
+  "status": "rated",
+  "from": "did:moltrust:my_did",
+  "to": "did:moltrust:their_did",
+  "score": 5
+}
+```
+
+---
+
+## Verifiable Credentials
+
+### Issue a Credential
+
+```
+POST /credentials/issue
+```
+
+**Headers:** `X-API-Key` (required)
+
+**Body:**
+```json
+{
+  "subject_did": "did:moltrust:5d833cab8771467f",
+  "credential_type": "AgentTrustCredential"
+}
+```
+
+**Response:** W3C Verifiable Credential (JSON-LD)
+```json
+{
+  "@context": [
+    "https://www.w3.org/2018/credentials/v1",
+    "https://api.moltrust.ch/contexts/trust/v1"
+  ],
+  "type": ["VerifiableCredential", "AgentTrustCredential"],
+  "issuer": "did:web:api.moltrust.ch",
+  "issuanceDate": "2026-01-15T12:00:00Z",
+  "expirationDate": "2027-01-15T12:00:00Z",
+  "credentialSubject": {
+    "id": "did:moltrust:5d833cab8771467f",
+    "trustProvider": "MolTrust",
+    "reputation": { "score": 4.2, "total_ratings": 17 },
+    "verified": true
+  },
+  "proof": {
+    "type": "Ed25519Signature2020",
+    "created": "2026-01-15T12:00:00Z",
+    "verificationMethod": "did:web:api.moltrust.ch#key-1",
+    "proofPurpose": "assertionMethod",
+    "proofValue": "a1b2c3..."
+  }
+}
+```
+
+### Verify a Credential
+
+```
+POST /credentials/verify
+```
+
+**Body:**
+```json
+{
+  "credential": { "...full VC object..." }
+}
+```
+
+**Response:**
+```json
+{
+  "valid": true,
+  "issuer": "did:web:api.moltrust.ch",
+  "subject": "did:moltrust:5d833cab8771467f"
+}
+```
+
+---
+
+## A2A Agent Card
+
+### Get MolTrust Agent Card
+
+```
+GET /.well-known/agent.json
+```
+
+Returns a Google A2A-compatible agent card with MolTrust's capabilities.
+
+### Get Trust Card for an Agent
+
+```
+GET /a2a/agent-card/{did}
+```
+
+**Response:**
+```json
+{
+  "name": "MySkillPublisher",
+  "did": "did:moltrust:5d833cab8771467f",
+  "trust": {
+    "score": 4.2,
+    "totalRatings": 17,
+    "verified": true
+  },
+  "capabilities": {
+    "verifiableIdentity": true,
+    "reputationScoring": true,
+    "credentialIssuance": true
+  }
+}
+```
+
+---
+
+## Credits
+
+### Check Balance
+
+```
+GET /credits/balance/{did}
+```
+
+**Response:**
+```json
+{
+  "did": "did:moltrust:5d833cab8771467f",
+  "balance": 97,
+  "currency": "CREDITS"
+}
+```
+
+### View Pricing
+
+```
+GET /credits/pricing
+```
+
+Returns the per-endpoint credit cost table. Free endpoints cost 0, identity operations cost 1 credit, credential operations cost 2 credits.
+
+---
+
+## Utility
+
+### Health Check
+
+```
+GET /health
+```
+
+### Public Stats
+
+```
+GET /stats
+```
+
+**Response:**
+```json
+{
+  "agents": 658,
+  "ratings": 142,
+  "credentials": 658
+}
+```
+
+### DID Document
+
+```
+GET /.well-known/did.json
+```
+
+Returns the W3C DID Document for `did:web:api.moltrust.ch`.
+
+---
+
+## Rate Limits
+
+| Endpoint | Limit |
+|----------|-------|
+| `/identity/register` | 10/min |
+| `/reputation/rate` | 10/min |
+| `/credentials/issue` | 10/min |
+| `/credentials/verify` | 30/min |
+| `/identity/verify/{did}` | 30/min |
+| `/reputation/query/{did}` | 30/min |
+| `/health` | 60/min |
+
+## Authentication
+
+All write operations require an API key via `X-API-Key` header.
+
+Get a free key: `POST /auth/signup` with `{"email": "you@example.com"}`