Build OneSource Docs Skill

A Claude Code skill plugin that embeds OneSource API knowledge directly into Claude's context window — teaching it how to write correct GraphQL queries, understand schema relationships, and avoid common pitfalls. This is the "how" complement to the Mach10 skill's "do."

Overview

The OneSource ecosystem currently has a gap: the MCP docs server (onesource-docs in .mcp.json) delivers raw documentation via fetch_docs, but no skill tells Claude what to fetch or how to interpret it. The Docs Skill closes this gap by providing structured API knowledge in-context — authentication patterns, all 12 root GraphQL queries, schema concepts, deprecated query tombstones, and integration examples.

Test data supports this: readability testing shows docs-in-context improves AI accuracy from 89% baseline to 96%. The skill targets >= 96% on the existing 55-question test suite.

llms.txt / llms-full.txt     <-- Source content (public docs, AI-optimized)
        |
        v
.mcp.json (onesource-docs)  <-- Phase 1: mcpdoc serves llms.txt via MCP
        |
        v
Docs Skill (skill.md)       <-- THIS: teaches Claude what/how to query
        |
        v
Mach10 Skill + MCP Server   <-- Execution: runs queries via mach10_graphql

Problem Statement

No structured guidance for Claude. The MCP docs server serves raw llms.txt content, but Claude must figure out correct query patterns on its own. This leads to errors (e.g., the universal Query 2.1 failure where all models generate nft() instead of the correct query shape).
Discovery bottleneck. GPT-4o has only 20% discovery rate for llms.txt — models that can't find docs get 89% accuracy vs 96%+ with docs in context. A skill eliminates the discovery problem entirely.
Dual-API confusion potential. The public federation API (api.onesource.io, BP- keys) and internal SRE-Dash API (api-sre-dash.onesource.io, sk_ keys) use different schemas. Without clear boundaries, Claude may mix query patterns across APIs.

Proposed Solution

Build a skill-only plugin at onesource-claude/plugins/onesource-docs/ that:

Embeds the public OneSource API schema knowledge in Claude's context
Uses modular structure (skill.md + sub-documents) following the Mach10 skill pattern
Includes explicit API boundary statements to prevent cross-API confusion
Contains deprecated query tombstones to override Claude's training-data biases
References the existing onesource-docs MCP server for deeper lookups when needed
Is self-sufficient — works without the MCP server configured

Technical Approach

Architecture

onesource-claude/plugins/onesource-docs/
  plugin.json                    # Plugin manifest (skill-only, no server)
  README.md                      # Installation and usage guide
  skills/
    onesource-docs/
      skill.md                   # Main entry point (~3K tokens, core patterns)
      docs/
        api-reference.md         # Complete query reference (all 12 root queries)
        schema-concepts.md       # Pagination, filtering, ordering, field selection
        authentication.md        # Endpoints, API keys, chains, rate limits
      examples/
        basic-queries.md         # One example per root query
        integration-patterns.md  # JS fetch, Axios, Python, Apollo Client, curl
        multi-step-workflows.md  # Dashboard building, wallet analysis
      troubleshooting/
        common-errors.md         # 401, null responses, wrong query shapes
        deprecated-queries.md    # Tombstones: queries that no longer exist

Content Strategy

Source material: static/llms-full.txt (public API, old schema) — NOT the Mach10 skill (internal API, new schema).

Token budget: ~15K tokens total across all files:

skill.md: ~3K tokens (trigger conditions, quick reference, key patterns, links to sub-docs)
docs/: ~6K tokens (schema reference, auth, concepts)
examples/: ~4K tokens (query examples, integration code)
troubleshooting/: ~2K tokens (errors, tombstones)

This is about half the Mach10 skill's footprint (~30K), leaving room for both skills to coexist in context.

Implementation Phases

Phase 1: Schema Verification & Content Prep (Pre-requisite)

Verify which schema the public federation API actually uses before writing any skill content.

Query the public API introspection endpoint to confirm schema shape

curl -X POST "https://api.onesource.io/federation/ethereum/graphql" \
  -H "Content-Type: application/json" \
  -H "x-bp-token: BP-{key}" \
  -d '{"query": "{ __schema { queryType { fields { name } } } }"}'

Document which queries exist on the public API (old schema's 12 queries vs Mach10's 12)
Confirm pagination pattern (items vs entries, edges/node vs flat entries)
Confirm filter pattern (filter: vs where:, flat suffixes vs nested ranges)
Clean llms-full.txt of Docusaurus JSX artifacts (import React, <ZoomImage>, :::tip)
Run the existing 55-question test suite with cleaned llms-full.txt as context to establish the actual baseline for the public API schema

Files involved:

static/llms-full.txt — source content to audit
scripts/ai-readability-test/data/test-queries.json — validators to check against confirmed schema

Blocking: All subsequent phases depend on this. If the public API has migrated to the new schema, the test suite validators must be updated before proceeding.

Phase 2: Plugin Scaffold & skill.md Core (Foundation)

Create the plugin directory structure and write the main skill.md.

Create onesource-ai-tools/onesource-claude/plugins/onesource-docs/ directory tree

Write plugin.json manifest

{
  "name": "onesource-docs",
  "version": "1.0.0",
  "description": "OneSource API documentation skill — teaches Claude how to write correct GraphQL queries against the public OneSource API",
  "author": { "name": "OneSource Team" },
  "skills": [
    {
      "name": "onesource-docs",
      "description": "Guide for understanding and querying the OneSource Web3 GraphQL API. Use when writing queries against api.onesource.io, understanding schema types, or troubleshooting API issues. NOT for mach10_graphql tool — use the Mach10 skill for that.",
      "path": "skills/onesource-docs/skill.md"
    }
  ],
  "commands": [],
  "mcpServers": []
}

Write skill.md with these sections:
1. Title + API Boundary Statement — "This skill covers the public OneSource API at api.onesource.io/federation/{chain}/graphql with x-bp-token: BP-... authentication. For the internal SRE-Dash API via mach10_graphql, use the Mach10 skill instead."
2. When to Use This Skill — trigger conditions (user mentions OneSource, api.onesource.io, BP- keys, GraphQL queries for blockchain data)
3. Conflict Resolution — "If the user is working with mach10_graphql, defer to the Mach10 skill. If the user mentions x-bp-token, BP- keys, api.onesource.io, or the federation endpoint, use this skill."
4. Quick Reference Table — all 12 root queries with one-line descriptions
5. Authentication Quick Start — endpoint format, header, key format, example curl
6. Key Schema Concepts Summary — pagination, filtering, ordering (brief, with links to sub-docs)
7. Common Pitfalls — top 3-5 errors (NFT query confusion, wrong timestamp format, etc.)
8. MCP Server Integration — how to use fetch_docs for deeper lookups (if configured)
9. Links to Sub-Documents — organized by docs/, examples/, troubleshooting/
Write README.md with installation instructions, prerequisites, and relationship to Mach10 plugin

Files to create:

plugins/onesource-docs/plugin.json
plugins/onesource-docs/README.md
plugins/onesource-docs/skills/onesource-docs/skill.md

Phase 3: Reference Documentation (Core Content)

Write the sub-documents under docs/.

docs/api-reference.md — All 12 root queries with:
- Query signature (arguments, types)
- Available fields on the return type
- Filter input type (with all fields)
- Ordering enum values
- One minimal example query with variables
- Expected response shape (abbreviated)
docs/schema-concepts.md — Cross-cutting patterns:
- Cursor-based pagination (first, after, pageInfo, totalCount)
- Nested range filters (timestamp, blockNumber, value ranges)
- Field selection and nested types (TokenAmount, Address interfaces, etc.)
- Enum reference (OrderDirection, TransactionStatus, AssetType/Standard)
- Response envelope structure
docs/authentication.md — Everything about connecting:
- Endpoint URL pattern: https://api.onesource.io/federation/{chain}/graphql
- Supported chains: ethereum, base, optimism, avax, sepolia, shape
- API key format: BP-{uuid} in x-bp-token header
- Subscription plans (Free, Starter, Pro) — rate limits and features
- CORS and browser usage notes

Files to create:

plugins/onesource-docs/skills/onesource-docs/docs/api-reference.md
plugins/onesource-docs/skills/onesource-docs/docs/schema-concepts.md
plugins/onesource-docs/skills/onesource-docs/docs/authentication.md

Phase 4: Examples & Integration Patterns

Write the sub-documents under examples/.

examples/basic-queries.md — One complete example per root query:
- GraphQL query string
- Variables object
- Expected response (abbreviated)
- Notes on gotchas for that specific query
examples/integration-patterns.md — Working code in 4 formats:
- JavaScript fetch() — basic POST with headers
- JavaScript Axios — same query via Axios
- Python requests — same query in Python
- Apollo Client — setup + query execution
- curl — command-line example
- Pagination loop pattern (JS and Python)
examples/multi-step-workflows.md — Real-world patterns:
- "Analyze a wallet" — get address → get balances → get recent transactions
- "Track whale movements" — filter high-value transactions → resolve addresses
- "Token dashboard" — get token details → top holders → recent transfers
- "NFT collection overview" — get contract → list NFTs → metadata + media

Files to create:

plugins/onesource-docs/skills/onesource-docs/examples/basic-queries.md
plugins/onesource-docs/skills/onesource-docs/examples/integration-patterns.md
plugins/onesource-docs/skills/onesource-docs/examples/multi-step-workflows.md

Phase 5: Troubleshooting & Tombstones

Write the sub-documents under troubleshooting/.

troubleshooting/common-errors.md — Error patterns and fixes:
- 401 Unauthorized — wrong key format, missing header, expired key
- Null response — querying wrong type (e.g., EOA address as contract)
- Empty results — wrong chain, wrong filter syntax, case sensitivity
- Pagination issues — using skip instead of cursor, missing pageInfo
- Field not found — using new-schema field names on old-schema API (or vice versa)
- GraphQL error response structure — {"errors": [{"message": "...", "locations": [...]}]}
troubleshooting/deprecated-queries.md — Tombstones with prominent warnings:
- List every query/pattern that Claude's training data might suggest but that is wrong
- For each: what Claude might generate, why it's wrong, what to use instead
- NFT query confusion (first entry, most prominent) — explain the correct pattern with a callout
- Old field names that were renamed
- Old filter syntax patterns

Files to create:

plugins/onesource-docs/skills/onesource-docs/troubleshooting/common-errors.md
plugins/onesource-docs/skills/onesource-docs/troubleshooting/deprecated-queries.md

Phase 6: Registration & Validation

Add onesource-docs entry to onesource-claude/.claude-plugin/marketplace.json

Run 55-question test suite with the Docs Skill content as context

cd scripts/ai-readability-test
npx tsx src/index.ts run --provider anthropic --mode readability --model claude-sonnet-4-20250514
npx tsx scripts/score-mcp-sim.ts --mode readability

Check: accuracy >= 96% (211+ out of 220 points)?
If below target: identify failing questions, update skill content, re-run
Run MCP-live test to validate skill + MCP server combination
```
npx tsx src/index.ts mcp-live -m deepseek-coder --quick
```

Files to modify:

onesource-ai-tools/onesource-claude/.claude-plugin/marketplace.json

Files to reference:

scripts/ai-readability-test/data/test-queries.json — test validators
scripts/ai-readability-test/results/reports/mcp-phase1-validation.md — fill in TBD fields

Alternative Approaches Considered

1. Monolithic skill.md (Rejected)

Put all content in a single skill.md file like some simpler skills do.

Why rejected: The Mach10 skill (889 lines, ~30K tokens) already proves that comprehensive API docs are too large for a single file. Modular structure allows Claude to load the core skill quickly and fetch details on demand. It also follows the established pattern.

2. Wrapper around Mach10 skill content (Rejected)

Adapt the Mach10 skill's content for the public API endpoint.

Why rejected: The Mach10 skill documents the NEW SRE-Dash schema, which differs significantly from the public API's schema. Copying and adapting would introduce errors at every divergence point. Content should be sourced from llms-full.txt (which documents the public API) instead.

3. MCP-only approach — no skill (Rejected)

Rely entirely on the onesource-docs MCP server (fetch_docs) to deliver content on demand.

Why rejected: Test data shows that docs-in-context (skill approach) achieves 96% accuracy vs lower rates when Claude must discover and interpret docs on its own. The skill provides structured, pre-interpreted knowledge that eliminates navigation overhead.

4. Combined Docs + Execution skill (Rejected)

Merge the Docs Skill and Mach10 Skill into one plugin.

Why rejected: They cover different APIs (public vs internal) with different schemas, auth, and endpoints. Combining them would increase context size (~45K+ tokens) and create confusion about which API a query targets. Clean separation with explicit boundary statements is safer.

Acceptance Criteria

Functional Requirements

Plugin installs correctly via marketplace (/plugin install onesource-docs@onesource-claude)
skill.md loads into Claude's context when relevant queries are detected
All 12 root GraphQL queries are documented with parameters, filters, and examples
Deprecated query tombstones prevent Claude from suggesting removed/incorrect queries
Authentication section covers endpoint format, API key format, and all 6 supported chains
Integration examples work in JavaScript (fetch, Axios, Apollo), Python (requests), and curl
Troubleshooting covers the top error patterns found in testing
Explicit API boundary statement prevents confusion with Mach10 skill

Non-Functional Requirements

Total token footprint ≤ 15K tokens across all files
skill.md (entry point) ≤ 3K tokens — fast to load
Self-sufficient — works without the MCP docs server configured
All code examples are syntactically valid and copy-pasteable
No Docusaurus JSX artifacts in any skill content

Quality Gates

55-question test suite: >= 96% accuracy (211+ / 220 points)
No regressions on previously passing questions
Query 2.1 (NFT lookup) specifically addressed by tombstone/correction
Both Docs + Mach10 skills loaded simultaneously produce no conflicting guidance

Success Metrics

Metric	Target	How to Measure
Test accuracy	>= 96%	Run readability test suite with skill as context
Token footprint	≤ 15K total	Count tokens across all skill files
Query 2.1 fix	Pass	Previously universal failure, should now pass
Install friction	Zero errors	Fresh install from marketplace on clean config
Dual-skill safety	No conflicts	Load both skills, run 10 representative queries

Dependencies & Prerequisites

Blocking Dependencies

Dependency	Status	Owner	Impact if Unresolved
Schema verification (public API)	Not started	Dev team	Cannot write accurate query examples
Clean `llms-full.txt`	Not started	Docs team	JSX artifacts will pollute skill content
Test suite alignment check	Not started	QA	May need validator updates for new schema

Non-Blocking Dependencies

Dependency	Status	Impact
MCP docs server configured	Done (`.mcp.json`)	Skill works without it, but enhanced with it
Marketplace registration	Not started	Needed for install, not for development
Phase 2 MCP tools	Not started	Forward-compat notes only, not required

Risk Analysis & Mitigation

Risk 1: Schema Mismatch (High Impact, Medium Probability)

Risk: The public API has migrated to the new schema but llms-full.txt hasn't been updated, causing the skill to teach outdated patterns.

Mitigation: Phase 1 introspection query confirms the actual schema before any content is written. If the public API has migrated, update llms-full.txt first, then write the skill.

Risk 2: Test Suite / Skill Misalignment (High Impact, Medium Probability)

Risk: The 55-question test validators expect old-schema answers but the skill teaches new-schema patterns (or vice versa), making 96% target unreachable.

Mitigation: Phase 1 includes running the test suite against confirmed schema to identify mismatches. Update validators if needed before Phase 6 validation.

Risk 3: Dual-Skill Conflict (Medium Impact, High Probability)

Risk: Users with both Docs and Mach10 skills get mixed API guidance.

Mitigation: Explicit API boundary statement in skill.md line 1. Conflict resolution rules in Section 3 of skill.md. Plugin description in plugin.json explicitly says "NOT for mach10_graphql."

Risk 4: Context Window Pressure (Medium Impact, Medium Probability)

Risk: Both skills loaded = ~45K tokens consumed before conversation starts.

Mitigation: Target 15K token budget (half of Mach10). Keep skill.md compact (~3K) with links to sub-docs. Claude loads sub-docs only when needed.

Risk 5: NFT Query Confusion Persists (Low Impact, High Probability)

Risk: Even with tombstones, Claude reverts to training-data patterns for NFT queries.

Mitigation: Make the NFT tombstone the FIRST entry in deprecated-queries.md, use a prominent callout format, and include it in skill.md Common Pitfalls section (double coverage).

Future Considerations

Phase 2 MCP Tools (Forward Compatibility)

The skill should include a brief "Future Tools" section noting that these tools are planned but NOT yet available:

Tool	Purpose	Status
`search_docs`	Semantic search across all documentation	Planned
`get_query_reference`	Full reference for a specific GraphQL query	Planned
`get_type_definition`	Schema definition for a GraphQL type	Planned
`list_examples`	Working examples filtered by topic	Planned

Frame as: "When these tools become available, use them for detailed lookups instead of fetch_docs. Do not attempt to call them until they are registered as available MCP tools."

Distribution Channels

Once validated, the skill should be published to:

NPM as @onesource/docs-skill (planned)
ClawHub agent marketplace (planned)
Skill.sh skill registry (planned)

Content Sync Pipeline

Long-term, the skill content should auto-generate from llms-full.txt so docs updates propagate to the skill without manual editing. This is out of scope for v1.

Documentation Plan

README.md in plugin root — installation, prerequisites, usage, relationship to other plugins
Update ONESOURCE-AI-TOOLS-CATALOG.md — change status from "~0% (planned)" to "~100% (complete)" and fill in details
Update memory/mcp-phase1.md — mark "Build a skill" as complete
Fill in scripts/ai-readability-test/results/reports/mcp-phase1-validation.md TBD fields with test results

References & Research

Internal References

Mach10 skill (reference implementation): onesource-ai-tools/onesource-claude/plugins/mcp-mach10/skills/mach10/skill.md
Mach10 plugin.json (manifest pattern): onesource-ai-tools/onesource-claude/plugins/mcp-mach10/plugin.json
Plugin conventions: onesource-ai-tools/onesource-claude/CLAUDE.md
Marketplace registry: onesource-ai-tools/onesource-claude/.claude-plugin/marketplace.json
MCP server config: .mcp.json (project root)
Source content: static/llms-full.txt
Test suite: scripts/ai-readability-test/data/test-queries.json
Test report: scripts/ai-readability-test/LLM-DISCOVERABILITY-REPORT.md
Catalog: ONESOURCE-AI-TOOLS-CATALOG.md (lines 290-467)
MCP phase 1 notes: memory/mcp-phase1.md

Key Findings from Research

Readability improvement: 89% baseline → 96% with docs in context (from LLM discoverability report)
Universal failure: Query 2.1 (NFT lookup) fails in every model — needs explicit tombstone
Biggest test gains: Integration Patterns (+16%), Troubleshooting (+14%), Core API Knowledge (+14%)
Token efficiency: Skill-in-context eliminates discovery overhead (no web fetches needed)
Thin connector pattern: Keep server minimal, put all knowledge in the skill (from CLAUDE.md best practices)
Schema divergence: Public API (llms-full.txt) uses different schema than internal API (Mach10 skill) — content must be sourced from llms-full.txt

Critical Questions (to resolve in Phase 1)

Which schema does the public API currently use? — Introspection query will confirm
Do test validators need updating? — Depends on schema answer
How stale is llms-full.txt? — Compare against live API introspection

File Summary

Files to Create (11)

File	Purpose	Token Budget
`plugins/onesource-docs/plugin.json`	Plugin manifest	~100
`plugins/onesource-docs/README.md`	Installation guide	~500
`plugins/onesource-docs/skills/onesource-docs/skill.md`	Main skill entry point	~3,000
`plugins/onesource-docs/skills/onesource-docs/docs/api-reference.md`	All 12 queries	~3,000
`plugins/onesource-docs/skills/onesource-docs/docs/schema-concepts.md`	Pagination, filters, ordering	~2,000
`plugins/onesource-docs/skills/onesource-docs/docs/authentication.md`	Endpoints, keys, chains	~1,000
`plugins/onesource-docs/skills/onesource-docs/examples/basic-queries.md`	One example per query	~2,000
`plugins/onesource-docs/skills/onesource-docs/examples/integration-patterns.md`	JS/Python/curl code	~1,500
`plugins/onesource-docs/skills/onesource-docs/examples/multi-step-workflows.md`	Real-world patterns	~1,000
`plugins/onesource-docs/skills/onesource-docs/troubleshooting/common-errors.md`	Error patterns	~1,000
`plugins/onesource-docs/skills/onesource-docs/troubleshooting/deprecated-queries.md`	Tombstones	~800

Files to Modify (2)

File	Change
`onesource-ai-tools/onesource-claude/.claude-plugin/marketplace.json`	Add onesource-docs plugin entry
`ONESOURCE-AI-TOOLS-CATALOG.md`	Update status from planned to complete

Overview​

Problem Statement​

Proposed Solution​

Technical Approach​

Architecture​

Content Strategy​

Implementation Phases​

Phase 1: Schema Verification & Content Prep (Pre-requisite)​

Phase 2: Plugin Scaffold & skill.md Core (Foundation)​

Phase 3: Reference Documentation (Core Content)​

Phase 4: Examples & Integration Patterns​

Phase 5: Troubleshooting & Tombstones​

Phase 6: Registration & Validation​

Alternative Approaches Considered​

1. Monolithic skill.md (Rejected)​

2. Wrapper around Mach10 skill content (Rejected)​

3. MCP-only approach — no skill (Rejected)​

4. Combined Docs + Execution skill (Rejected)​

Acceptance Criteria​

Functional Requirements​

Non-Functional Requirements​

Quality Gates​

Success Metrics​

Dependencies & Prerequisites​

Blocking Dependencies​

Non-Blocking Dependencies​

Risk Analysis & Mitigation​

Risk 1: Schema Mismatch (High Impact, Medium Probability)​

Risk 2: Test Suite / Skill Misalignment (High Impact, Medium Probability)​

Risk 3: Dual-Skill Conflict (Medium Impact, High Probability)​

Risk 4: Context Window Pressure (Medium Impact, Medium Probability)​

Risk 5: NFT Query Confusion Persists (Low Impact, High Probability)​

Future Considerations​

Phase 2 MCP Tools (Forward Compatibility)​

Distribution Channels​

Content Sync Pipeline​

Documentation Plan​

References & Research​

Internal References​

Key Findings from Research​

Critical Questions (to resolve in Phase 1)​

File Summary​

Files to Create (11)​

Files to Modify (2)​

Overview

Problem Statement

Proposed Solution

Technical Approach

Architecture

Content Strategy

Implementation Phases

Phase 1: Schema Verification & Content Prep (Pre-requisite)

Phase 2: Plugin Scaffold & skill.md Core (Foundation)

Phase 3: Reference Documentation (Core Content)

Phase 4: Examples & Integration Patterns

Phase 5: Troubleshooting & Tombstones

Phase 6: Registration & Validation

Alternative Approaches Considered

1. Monolithic skill.md (Rejected)

2. Wrapper around Mach10 skill content (Rejected)

3. MCP-only approach — no skill (Rejected)

4. Combined Docs + Execution skill (Rejected)

Acceptance Criteria

Functional Requirements

Non-Functional Requirements

Quality Gates

Success Metrics

Dependencies & Prerequisites

Blocking Dependencies

Non-Blocking Dependencies

Risk Analysis & Mitigation

Risk 1: Schema Mismatch (High Impact, Medium Probability)

Risk 2: Test Suite / Skill Misalignment (High Impact, Medium Probability)

Risk 3: Dual-Skill Conflict (Medium Impact, High Probability)

Risk 4: Context Window Pressure (Medium Impact, Medium Probability)

Risk 5: NFT Query Confusion Persists (Low Impact, High Probability)

Future Considerations

Phase 2 MCP Tools (Forward Compatibility)

Distribution Channels

Content Sync Pipeline

Documentation Plan

References & Research

Internal References

Key Findings from Research

Critical Questions (to resolve in Phase 1)

File Summary

Files to Create (11)

Files to Modify (2)