feat: add build tooling, sanitize sensitive literals, and fix docs

- Add unified build script (build.js) with CI workflow (.github/workflows/validate.yml)
- Add sensitive literal scanner and sanitizer scripts
- Add markdown link checker script
- Improve generator: typed placeholders for all field types, skip empty query params in curl examples
- Sanitize all rule and reference files to use placeholder addresses/hashes
- Move ApiResponseCodes.md and SpamDetection.md from rules/ to references/
- Fix test-installation.sh missing exit 1 on failures
- Fix streams docs using addressToAdd instead of address
- Align CONTRIBUTING.md frontmatter example with actual schema
- Update CLAUDE.md architecture tree with new reference files
- Bump versions: moralis-data-api 1.4.0, moralis-streams-api 1.3.0, learn-moralis 1.2.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: novnski

.github/workflows/validate.yml

@@ -0,0 +1,25 @@
+name: Validate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Run Build Validation
+        run: node scripts/build.js
+
+      - name: Ensure Generated Files Are Committed
+        run: git diff --exit-code

CLAUDE.md

@@ -18,9 +18,10 @@ skills/
 │   │   ├── ProductComparison.md
 │   │   └── UseCaseGuide.md
 │   └── SKILL.md
-├── moralis-data-api/           # Unified EVM + Solana data API (135 endpoints)
+├── moralis-data-api/           # Unified EVM + Solana data API (136 endpoints)
 │   ├── rules/                  # Auto-generated endpoint docs (one per endpoint)
 │   ├── references/
+│   │   ├── ApiResponseCodes.md       # API response code patterns and handling guidance
 │   │   ├── CommonPitfalls.md         # Gotchas: data types, HTTP methods, path inconsistencies
 │   │   ├── DataTransformations.md    # Type conversions, field mappings, snake_case → camelCase
 │   │   ├── DefiProtocols.md          # Supported DeFi protocols and chains
@@ -31,6 +32,7 @@ skills/
 │   │   ├── ResponsePatterns.md       # Pagination patterns and response wrapper structures
 │   │   ├── SupportedApisAndChains.md # Chain support matrix
 │   │   ├── SupportedDexs.md          # Supported DEXs for token API endpoints
+│   │   ├── SpamDetection.md          # Spam flag interpretation and filtering guidance
 │   │   ├── TokenHoldersFaq.md        # Token Holders API FAQ and important notes
 │   │   ├── TokenSearch.md            # Token search functionality reference
 │   │   └── WalletHistory.md          # Wallet history categories and classifications
@@ -64,6 +66,7 @@ Each skill includes pattern reference files containing complete reference materi
 ### moralis-data-api
 
 - `references/CommonPitfalls.md` - Gotchas: data type assumptions, HTTP methods, path inconsistencies
+- `references/ApiResponseCodes.md` - API response code patterns, response handling, and retry guidance
 - `references/DataTransformations.md` - Type conversions, field mappings (block numbers, timestamps, balances, snake_case → camelCase)
 - `references/DefiProtocols.md` - Supported DeFi protocols and chains for position endpoints
 - `references/FilteredTokens.md` - Token discovery metrics, timeframes, and filter examples
@@ -73,6 +76,7 @@ Each skill includes pattern reference files containing complete reference materi
 - `references/ResponsePatterns.md` - Pagination patterns and response wrapper structures
 - `references/SupportedApisAndChains.md` - Chain support matrix
 - `references/SupportedDexs.md` - Supported DEXs for token API endpoints
+- `references/SpamDetection.md` - Spam flag interpretation, filtering behavior, and recommended handling
 - `references/TokenHoldersFaq.md` - Token Holders API FAQ and important notes
 - `references/TokenSearch.md` - Token search functionality reference
 - `references/WalletHistory.md` - Wallet history categories and classifications
@@ -99,6 +103,12 @@ Each skill includes pattern reference files containing complete reference materi
 ## Development Commands
 
 ```bash
+# One-shot build (preferred): generation + validation + non-API tests
+bun run build
+
+# Full build including API-key dependent tests
+bun run build:full
+
 # Generate endpoint markdown rules from swagger config
 node scripts/generate-endpoint-rules.js
 
@@ -120,6 +130,15 @@ node scripts/check-solana-suffix.js
 # Verify Solana endpoint variants are properly registered (ESM)
 node scripts/verify-solana-variants.mjs
 
+# Validate markdown references resolve correctly
+node scripts/check-markdown-links.js
+
+# Sanitize markdown docs by replacing address/hash-like literals with placeholders
+node scripts/sanitize-sensitive-literals.js
+
+# Validate no address/hash-like literals exist in markdown docs
+node scripts/check-sensitive-literals.js
+
 # Test all skills end-to-end
 bash scripts/test-all-skills.sh
 
@@ -148,6 +167,14 @@ node scripts/bump-version.js <skill|all> <major|minor|patch>
 - **EVM endpoints:** No suffix unless collision exists (then `__evm`)
 - This convention is strictly enforced by the generator script
 
+## Sensitive Literal Policy
+
+To avoid antivirus false positives in hosted skill content:
+
+- Never commit real-looking EVM addresses, transaction hashes, Solana addresses, or UUIDs in markdown files.
+- Always use placeholders such as `YOUR_EVM_ADDRESS`, `YOUR_SOLANA_ADDRESS`, `YOUR_TX_HASH`, and `YOUR_STREAM_ID`.
+- Run `node scripts/check-sensitive-literals.js` before reporting completion.
+
 ## Skill Versioning
 
 Skills use semver (`MAJOR.MINOR.PATCH`) in the `version` frontmatter field. Bump with `node scripts/bump-version.js`.

CONTRIBUTING.md

@@ -14,7 +14,7 @@ Thank you for your interest in contributing!
 
 1. Create directory: `skills/your-skill-name/`
 2. Create `SKILL.md` following the [Agent Skills Standard](https://github.com/agentskills/agentskills)
-3. Create reference documentation in `rules/`
+3. Add manual reference documentation in `references/` (endpoint `rules/` are generated)
 4. Test with a real API key using REST (curl or native HTTP)
 
 ### SKILL.md Format
@@ -25,23 +25,47 @@ Required frontmatter:
 ---
 name: your-skill-name
 description: What this skill does and when to use it
-tags: [web3, ...]
 version: 1.0.0
-author: MoralisWeb3
+metadata:
+  author: MoralisWeb3
 ---
 ```
 
 ### Testing
 
+Preferred one-shot validation:
+
+```bash
+bun run build
+```
+
+Optional full run (includes API-key dependent checks):
+
+```bash
+bun run build:full
+```
+
 ```bash
 # Set your API key
 export MORALIS_API_KEY="your_moralis_api_key"
 
 # Test a REST query
-curl "https://deep-index.moralis.io/api/v2.2/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045/balance?chain=0x1" \
+curl "https://deep-index.moralis.io/api/v2.2/YOUR_EVM_ADDRESS/balance?chain=0x1" \
   -H "X-API-Key: $MORALIS_API_KEY"
 ```
 
+### Sensitive Literal Policy (Required)
+
+Do not commit real-looking blockchain identifiers in markdown content.
+
+- Use placeholders only: `YOUR_EVM_ADDRESS`, `YOUR_SOLANA_ADDRESS`, `YOUR_TX_HASH`, `YOUR_STREAM_ID`
+- Never include real-looking EVM addresses (`0x...` 40 hex), transaction hashes, Solana addresses, or UUIDs
+- Before committing, run:
+
+```bash
+node scripts/check-sensitive-literals.js
+```
+
 ## Commit Guidelines
 
 - Use clear commit messages

README.md

@@ -74,11 +74,11 @@ Unified skill for all blockchain data queries. Auto-detects EVM vs Solana from a
 - **Solana** (34) — native Solana endpoints + EVM endpoints with Solana support
 
 ```
-/moralis-data-api Get the balance of 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+/moralis-data-api Get the balance of YOUR_EVM_ADDRESS
 
-/moralis-data-api Get the balance of 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 on Polygon
+/moralis-data-api Get the balance of YOUR_EVM_ADDRESS on Polygon
 
-/moralis-data-api Get the balance of Solana wallet 742d35Cc6634C0532925a3b844Bc9e7595f0bEb
+/moralis-data-api Get the balance of Solana wallet YOUR_SOLANA_ADDRESS
 ```
 
 > **Tip:** Prefix your prompt with the skill name (e.g. `/moralis-data-api`) to load it directly. Some agents auto-detect skills, but tagging ensures it works across all agents.
@@ -92,7 +92,7 @@ Real-time blockchain event monitoring with webhooks. **20 endpoints** for creati
 ```
 /moralis-streams-api Create a stream to monitor all ERC20 transfers on Ethereum
 
-/moralis-streams-api Pause the stream with ID a1b2c3d4-e5f6-7890-abcd-ef1234567890
+/moralis-streams-api Pause the stream with ID YOUR_STREAM_ID
 ```
 
 ## learn-moralis
@@ -116,6 +116,7 @@ Knowledge-only skill for answering general questions about Moralis. Routes users
 - **Zero dependencies** — all API calls use curl
 - **Works with 18+ agents** — any agent supporting the [Agent Skills](https://skills.sh/) standard
 - **Auto-generated endpoint docs** — `swagger/api-configs.json` → `scripts/generate-endpoint-rules.js` → `rules/*.md`
+- **Sanitized examples** — markdown docs use placeholders (`YOUR_EVM_ADDRESS`, etc.) to avoid shipping real-looking identifiers
 - **Manually maintained references** — pattern files in each skill's `references/` directory
 
 ## Documentation

package.json

@@ -0,0 +1,8 @@
+{
+  "name": "onchain-skills",
+  "private": true,
+  "scripts": {
+    "build": "node scripts/build.js",
+    "build:full": "node scripts/build.js --with-api-tests"
+  }
+}

scripts/build.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const ROOT = path.join(__dirname, "..");
+
+function runStep(name, cmd, args) {
+  console.log(`\n==> ${name}`);
+  const result = spawnSync(cmd, args, {
+    cwd: ROOT,
+    stdio: "inherit",
+    shell: false,
+  });
+
+  if (result.status !== 0) {
+    if (result.status === null && result.signal) {
+      console.error(`Step "${name}" terminated by signal ${result.signal}`);
+      process.exit(1);
+    }
+    process.exit(result.status || 1);
+  }
+}
+
+function hasApiKeyContext() {
+  if (process.env.MORALIS_API_KEY) return true;
+  if (fs.existsSync(path.join(ROOT, ".env"))) return true;
+  if (fs.existsSync(path.join(ROOT, ".claude/.env"))) return true;
+  return false;
+}
+
+function main() {
+  const withApiTests = process.argv.includes("--with-api-tests");
+
+  const steps = [
+    ["Generate endpoint rules", "node", ["scripts/generate-endpoint-rules.js"]],
+    ["Check collision mapping", "node", ["scripts/check-collisions.js"]],
+    [
+      "Check all collision files",
+      "node",
+      ["scripts/check-all-collisions.mjs"],
+    ],
+    ["Check Solana suffixes", "node", ["scripts/check-solana-suffix.js"]],
+    ["Verify Solana variants", "node", ["scripts/verify-solana-variants.mjs"]],
+    ["Check markdown links", "node", ["scripts/check-markdown-links.js"]],
+    [
+      "Check sensitive literals",
+      "node",
+      ["scripts/check-sensitive-literals.js"],
+    ],
+    ["Test installation layout", "bash", ["scripts/test-installation.sh"]],
+    ["Run bug checks", "bash", ["scripts/test-bugs.sh"]],
+  ];
+
+  for (const [name, cmd, args] of steps) {
+    runStep(name, cmd, args);
+  }
+
+  if (withApiTests || hasApiKeyContext()) {
+    runStep("Run API-key dependent tests", "bash", ["scripts/test-all-skills.sh"]);
+  } else {
+    console.log(
+      "\n==> Skip API-key dependent tests (no MORALIS_API_KEY/.env detected)",
+    );
+    console.log("    Run `bun run build:full` to force this step.");
+  }
+
+  console.log("\nBuild completed successfully.");
+}
+
+main();

scripts/check-all-collisions.mjs

@@ -43,3 +43,5 @@ if (issues.length > 0) {
 } else {
   console.log('=== All collisions have both files ===');
 }
+
+process.exit(issues.length > 0 ? 1 : 0);

scripts/check-collisions.js

@@ -11,7 +11,6 @@ const data = JSON.parse(fs.readFileSync(API_CONFIGS_PATH, "utf8"));
 // Get all operationIds from each source
 const evmOps = new Set(Object.keys(data.evm || {}));
 const solanaOps = new Set(Object.keys(data.solana || {}));
-const streamsOps = new Set(Object.keys(data.streams || {}));
 
 // Find collisions between EVM and Solana
 const collisions = [];
@@ -69,3 +68,5 @@ if (missingFiles.length > 0) {
 if (missingSuffix.length === 0 && missingFiles.length === 0) {
   console.log("✅ All collision handling is correct!");
 }
+
+process.exit(missingSuffix.length > 0 || missingFiles.length > 0 ? 1 : 0);

scripts/check-markdown-links.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const SCAN_ROOTS = [
+  path.join(ROOT, "README.md"),
+  path.join(ROOT, "CLAUDE.md"),
+  path.join(ROOT, "CONTRIBUTING.md"),
+  path.join(ROOT, "skills"),
+];
+
+function shouldScan(filePath) {
+  return path.extname(filePath).toLowerCase() === ".md";
+}
+
+function* walk(targetPath) {
+  if (!fs.existsSync(targetPath)) return;
+
+  const stat = fs.statSync(targetPath);
+  if (stat.isFile()) {
+    if (shouldScan(targetPath)) yield targetPath;
+    return;
+  }
+
+  const entries = fs.readdirSync(targetPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(targetPath, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(fullPath);
+      continue;
+    }
+    if (entry.isFile() && shouldScan(fullPath)) {
+      yield fullPath;
+    }
+  }
+}
+
+function findBrokenLinks(filePath) {
+  const rel = path.relative(ROOT, filePath);
+  const text = fs.readFileSync(filePath, "utf8");
+  const issues = [];
+  const linkRegex = /\[[^\]]+\]\(([^)]+)\)/g;
+
+  for (const match of text.matchAll(linkRegex)) {
+    const raw = match[1].trim();
+    if (
+      raw.startsWith("http://") ||
+      raw.startsWith("https://") ||
+      raw.startsWith("mailto:") ||
+      raw.startsWith("#")
+    ) {
+      continue;
+    }
+
+    const local = raw.split("#")[0];
+    if (!local) continue;
+
+    const target = path.resolve(path.dirname(filePath), local);
+    if (!fs.existsSync(target)) {
+      issues.push(`${rel} -> ${raw}`);
+    }
+  }
+
+  return issues;
+}
+
+function main() {
+  const files = [];
+  for (const root of SCAN_ROOTS) {
+    for (const filePath of walk(root)) files.push(filePath);
+  }
+
+  const broken = [];
+  for (const filePath of files) {
+    broken.push(...findBrokenLinks(filePath));
+  }
+
+  if (broken.length === 0) {
+    console.log("All markdown relative links resolve.");
+    return;
+  }
+
+  console.error("Broken markdown links detected:");
+  for (const issue of broken) {
+    console.error("- " + issue);
+  }
+  process.exit(1);
+}
+
+main();