+
+
RealSkills API
+
+ Skills, proven in the wild — not declared on paper.
+
+
+ A living skills endpoint that evolves through agent conversations. Unlike static
+ documentation, skills emerge organically from question patterns and improve over time.
+
+
+
+ {/* Philosophy */}
+
+
+ Philosophy
+ Why living skills beats static skills.md
+
+
+
+ Traditional documentation is written once and becomes outdated. RealSkills takes a
+ different approach:
+
+
+
+ Questions drive discovery — Every agent question reveals what users
+ actually need
+
+
+ Answers compound — Similar questions get better answers based on
+ previous responses
+
+
+ Skills emerge — Patterns in questions automatically create skill
+ categories
+
+
+ Quality improves — More questions = more context = better responses
+
+
+
+ Think of it as a knowledge base that learns from every interaction.
+
+
+
+
+ {/* How It Works */}
+
+
+ How It Works
+ The question → skill inference loop
+
+
+
+
{`Agent POSTs question
+ ↓
+┌─────────────────────────────┐
+│ /skills endpoint │
+│ - Embed question │
+│ - Check similarity cache │
+│ - RAG from stored Q&A │
+│ - Generate response (LLM) │
+│ - Store question + answer │
+│ - Update skill graph │
+└─────────────────────────────┘
+ ↓
+ Return skill guidance (markdown)
+ ↓
+ Skill graph evolves in real-time`}
+
+
+ Question Received — Agent submits a question via POST
+
+
+ Embedding Generated — Question is converted to a 3072-dimensional
+ vector
+
+
+ Similarity Check — If >95% similar to existing question, return
+ cached answer
+
+
+ RAG Context — Find similar past questions/answers for context
+
+
+ Response Generation — GPT-4.1-mini generates a tailored response
+
+
+ Storage & Graph Update — Question stored, skills inferred and linked
+
+
+
+
+
+ {/* API Reference */}
+
+
+ API Reference
+ GET and POST endpoints
+
+
+
+
GET /:username/collections/:slug/skills
+
+ Returns the skill summary as markdown. Triggers lazy seeding on first access.
+
+
+
+
POST /:username/collections/:slug/skills
+
+ Submit a question and receive an AI-generated response based on the collection's
+ tools and previous Q&A.
+
+
+
+
+
+ {/* Request Schema */}
+
+
+ Request Schema
+ POST request body format
+
+
+
+
Multi-Turn Conversations
+
+ To continue a conversation, include the sessionId from a previous
+ response. Sessions maintain context for up to 24 hours and include the last 20
+ messages.
+
+
+
+
+ {/* Response Schema */}
+
+
+ Response Schema
+ Successful response format
+
+
+ Example Response
+
+
+
+ {/* Integration Guide */}
+
+
+ Integration Guide
+ How agents should use the Skills API
+
+
+ 1. Initial Discovery
+
+ When an agent first encounters a collection, fetch the skills summary:
+
+ 2. Asking Questions
+
+ When the agent needs guidance on using the tools:
+
+ 3. Multi-Turn Conversations
+
+ For follow-up questions, use the session ID:
+
+
+
+
+ {/* Best Practices */}
+
+
+ Best Practices
+ Effective questioning patterns
+
+
+
+
+
+ Good Questions
+
+
+ ✓ "How do I handle rate limiting with the API tool?"
+ ✓ "What's the best way to batch multiple requests?"
+ ✓ "Can I use these tools with streaming responses?"
+
+
+
+
+ Avoid These
+
+
+ ✗ "Tell me everything about this collection"
+ ✗ Single-word questions like "Help"
+ ✗ Questions unrelated to the collection's tools
+
+
+
+
Tips for Better Responses
+
+ • Be specific about what you're trying to accomplish
+ • Include relevant context in the context field
+ • Use tags to hint at the problem domain
+ • Use sessions for related follow-up questions
+
+
+
+
+ {/* Confidence Scores */}
+
+
+ Confidence Scores
+ How confidence is calculated
+
+
+
+ Each response includes a confidence score (0-1) based on:
+
+
+
+
+ Base confidence (30%) — Minimum for any generated response
+
+
+ Similar questions (up to 40%) — More similar past Q&A = higher
+ confidence
+
+
+ Skills documentation (20%) — Collection has generated skills.md
+
+
+ Question volume (10%) — 3+ similar questions adds bonus
+
+
+
+
+
Interpreting Scores
+
+
+ >0.8 — High confidence, well-supported by prior Q&A
+
+
+ 0.5-0.8 — Moderate confidence, some relevant context
+
+
+ <0.5 — Lower confidence, limited prior knowledge
+
+
+
+
+
+ {/* Lazy Seeding */}
+
+
+ Lazy Seeding
+ Automatic bootstrapping on first access
+
+
+
+ When a collection's skills endpoint is accessed for the first time, it automatically
+ seeds with synthetic questions generated from:
+
+
+
+ Existing skills.md documentation (if available)
+ Tool descriptions and capabilities
+ Common use case patterns for the tool category
+
+
+
+ This ensures the endpoint is useful immediately, even before any real agent interactions.
+ Seeding typically adds 10-15 synthetic Q&A pairs.
+
+
+
+
Seeding Status Response
+
+ If seeding is in progress when you make a request, you'll receive a 202 response:
+
+
+
+
+
+ {/* Caching */}
+
+
+ Caching Behavior
+ How similar questions are cached
+
+
+
+ Questions with >95% similarity to existing questions return cached answers instantly.
+ This provides:
+
+
+
+ Faster response times (~50ms vs ~1-2s)
+ Reduced API costs
+ Consistent answers for equivalent questions
+
+
+
+ The meta.cached field indicates whether a cached response was used. Cached
+ responses increment a similarCount counter for analytics.
+
+
+
+
+ {/* Next Steps */}
+
+
+ Next Steps
+ Continue exploring TPMJS
+
+
+
+
+
+ Automated testing for tool collections
+
+
+
+
+ Create and manage tool collections
+
+
+
+
+ Build AI agents with your collections
+
+
+
+
+ Discover tools to add to your collections
+
+
+
+
+
+