Using nested JSON Skillsets to save 90% of tokens with Cursor

How To
1

TL;DR

Store your domain expertise as structured JSON files instead of prose instructions. Your AI gets 10-25x faster context loading, perfect recall, and domain mastery. Here’s how I save 87% of tokens and stay in Auto mode with excellent performance:

The Problem

Your Cursor agent is smart, but:

  • Re-reads massive .cursorrules files every conversation (slow)
  • Forgets project-specific patterns between sessions
  • Guesses at API contracts instead of knowing them
  • No easy way to organize domain expertise by feature

The Solution: JSON Skillsets

Create .cursor/skillsets/ directory with domain-specific JSON files:

// .cursor/skillsets/payment-integration-skillset.json
{
  "name": "Payment Integration Specialist",
  "domain": "payment-processing",
  "expertise": ["wayforpay", "stripe", "webhook-validation"],
  "patterns": {
    "webhook_validation": {
      "description": "HMAC signature validation required",
      "code_template": "const isValid = validateHMAC(payload, signature, secret)",
      "security_notes": ["Never log payment data", "Server-side only"]
    }
  },
  "api_contracts": {
    "createPayment": {
      "params": ["amount", "currency", "orderId"],
      "returns": "{ success: boolean, paymentUrl: string }",
      "errors": ["INVALID_AMOUNT", "MISSING_CONFIG"]
    }
  },
  "common_mistakes": [
    "Assuming paths exist without verification",
    "Client-side secret key exposure"
  ]
}

How It Works

  1. Fast Lookup - 2ms JSON parse vs 100ms+ markdown scan
  2. Structured Knowledge - AI knows exactly where to find what
  3. Perfect Recall - API contracts, error codes, security rules
  4. Composable - One skillset per domain, mix and match

Implementation Guide

1. Create structure

mkdir -p .cursor/concepts

2. Extract domain knowledge

  • Move payment logic → payment-skillset.json
  • Move auth patterns → auth-skillset.json
  • Move DB operations → database-skillset.json

3. Create index

cat > .cursor/skillsets/index.json << EOF
{
  "agents": [
    {
      "id": "payment-specialist",
      "file": ".cursor/skillsets/payment-integration-skillset.json",
      "triggers": ["payment", "stripe", "checkout", "webhook"]
    }
  ]
}
EOF

4. Reference in .cursorrules

echo “Consult .cursor/skillsets/ nested json skillsets for domain expertise” >> .cursorrules

Real Results (Our Metrics)

  • Search: 51ms → 2ms (25x faster)
  • First-try success: 60% → 95%
  • Debug time: 30min → 2min (verification vs guessing)
  • Knowledge retention: 100% across context windows

Advanced: MCP Integration

We built Legion MCP tools that auto-query these skillsets:

// legion-agent-selector finds the right expert
const agent = await legion.selectAgent({
  task: "implement stripe webhook validation"
});
// Returns: payment-specialist with all patterns loaded

// legion-knowledge queries specific patterns
const pattern = await legion.knowledge({
  query: "webhook HMAC validation"
});
// Returns: exact code template + security notes

Pro tips:

  • Start small (3-4 skillsets)
  • Use descriptive keys (‘webhook_validation’ instead of ‘wv’)
  • Include actual code templates
  • Document what NOT to do (common mistakes)

Our Stack

We maintain 136 agents for ring-platform.org - Ring Platform (React 19/Next.js 15/Web3) and ConnectPlatform (Erlang/OTP 28 BaaS). Every feature has a specialist. Every specialist is a JSON file. Zero guesswork, zero wasted tokens.

1 Like
2

Here is a skillset example: nextjs-16-upgrader-skillset.json · GitHub
Use this lens of truth to upgrade your Next.js project to its latest version in no-sweat Auto mode.