colosseum-copilot

Preamble (run first)

_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//'  || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRY: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"colosseum-copilot","phase":"idea","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"colosseum-copilot","phase":"idea","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
true
fi

If TEL_PROMPTED is no: Before starting the skill workflow, ask the user about telemetry. Use AskUserQuestion:

Help superstack get better! We track which skills get used and how long they take — no code, no file paths, no PII. Change anytime in ~/.superstack/config.json.

Options:

• A) Sure, help superstack improve (anonymous)
• B) No thanks

If A: run this bash:

echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted

If B: run this bash:

echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted

This only happens once. If TEL_PROMPTED is yes, skip this entirely and proceed to the skill workflow.

Wrong skill? See SKILL_ROUTER.md for all available skills.

Colosseum Copilot

Overview

Search and analyze Colosseum’s database of 5,400+ Solana hackathon projects. Discover what winners do differently, find similar projects to your idea, explore ML-derived clusters, and access research archives — all powered by the Colosseum Copilot API.

Token Setup

Before using this skill, check if the user has a Colosseum Copilot token configured.

_COPILOT_TOKEN="${COLOSSEUM_COPILOT_PAT:-$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"copilotToken":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")}"
if [ -n "$_COPILOT_TOKEN" ]; then
  echo "TOKEN_STATUS: configured"
else
  echo "TOKEN_STATUS: missing"
fi

If TOKEN_STATUS is “missing”

Ask the user with AskUserQuestion:

Colosseum Copilot gives you access to 5,400+ Solana hackathon projects, winner patterns, and gap analysis.

To use it, you need a free Personal Access Token from Colosseum.

1. Sign up at https://arena.colosseum.org/copilot
2. Copy your Personal Access Token (PAT)

Options:

• A) I have a token — let me paste it
• B) Skip for now

If A: Ask for the token, then save it:

# Replace TOKEN_VALUE with the actual token the user provides
cat ~/.superstack/config.json 2>/dev/null | python3 -c "
import sys, json
try:
    config = json.load(sys.stdin)
except:
    config = {}
config['copilotToken'] = 'TOKEN_VALUE'
config['copilotTokenSetAt'] = '$(date -u +%Y-%m-%dT%H:%M:%SZ)'
config['copilotPrompted'] = True
print(json.dumps(config, indent=2))
" > ~/.superstack/config.json.tmp && mv ~/.superstack/config.json.tmp ~/.superstack/config.json
echo "Token saved to ~/.superstack/config.json"

Then verify:

curl -s -H "Authorization: Bearer TOKEN_VALUE" -H "Content-Type: application/json" https://copilot.colosseum.com/api/v1/status

If {"authenticated": true}, proceed. Otherwise, tell the user the token is invalid and ask them to check it.

If B: Tell the user they can set it later via:

• superstack copilot --token <pat> (CLI command)
• Or set COLOSSEUM_COPILOT_PAT environment variable
• Or run /colosseum-copilot again

Then end the skill — the remaining workflow requires a valid token.

If TOKEN_STATUS is “configured”

Verify the token is still valid:

curl -s -H "Authorization: Bearer $_COPILOT_TOKEN" -H "Content-Type: application/json" https://copilot.colosseum.com/api/v1/status

If not authenticated, tell the user their token has expired and walk them through the setup above.

Workflow

Read references/copilot-api-guide.md for the full API reference.

1. Determine intent — What does the user want?

   • Search: Find projects similar to their idea
   • Explore: Browse clusters and categories
   • Analyze: Understand winner patterns and gaps
   • Research: Find archived articles and papers
   • If unclear, ask.

2. Search similar projects — When the user has an idea or query:

   curl -s -X POST https://copilot.colosseum.com/api/v1/search/projects \
     -H "Authorization: Bearer $_COPILOT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query": "USER_QUERY", "limit": 8, "diversify": true}'

   Present results as a table: name, one-liner, hackathon, similarity score, prize info, crowdedness.

3. Gap analysis — Compare what winners do vs the field:

   curl -s -X POST https://copilot.colosseum.com/api/v1/compare \
     -H "Authorization: Bearer $_COPILOT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"cohortA": {"winnersOnly": true}, "cohortB": {}, "dimensions": ["problemTags", "solutionTags", "primitives"], "topK": 8}'

   Synthesize overindexed (winners focus on) and underindexed (winners skip) attributes. Present the delta clearly.

4. Explore clusters — Browse the 30 ML-derived project clusters:

   curl -s -H "Authorization: Bearer $_COPILOT_TOKEN" -H "Content-Type: application/json" https://copilot.colosseum.com/api/v1/filters

   Show: hot categories (most projects), winning categories (highest win rate), open categories (least crowded).

5. Deep dive into a project — When the user wants full details on a specific project:

   curl -s -H "Authorization: Bearer $_COPILOT_TOKEN" -H "Content-Type: application/json" \
     https://copilot.colosseum.com/api/v1/projects/by-slug/PROJECT_SLUG

   Shows: description, team members (GitHub/Twitter), links (demo, presentation, GitHub), full tag set.

6. Explore a specific cluster — Get cluster summary and representative projects:

   curl -s -H "Authorization: Bearer $_COPILOT_TOKEN" -H "Content-Type: application/json" \
     https://copilot.colosseum.com/api/v1/clusters/CLUSTER_KEY

   Shows: summary, project count, winner count, representative projects, top tags.

7. Search archives — Find research sources:

   curl -s -X POST https://copilot.colosseum.com/api/v1/search/archives \
     -H "Authorization: Bearer $_COPILOT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query": "USER_QUERY", "limit": 4, "maxChunksPerDoc": 1, "intent": "ideation"}'

   Present: title, author, source, published date, snippet.

8. Read full archive document — When a snippet is interesting and the user wants more:

   curl -s -H "Authorization: Bearer $_COPILOT_TOKEN" -H "Content-Type: application/json" \
     "https://copilot.colosseum.com/api/v1/archives/DOCUMENT_ID?maxChars=8000"

   Supports pagination via offset and nextOffset for long documents.

9. Synthesize — After gathering data, provide:

   • Top 5 most similar existing projects (with why they’re similar)
   • Gap analysis summary: what winners emphasize, what they skip
   • Crowdedness assessment for the user’s niche
   • Recommended differentiation angle based on gaps
   • Relevant research sources

Non-Negotiables

• Always verify the token before making API calls.
• Use a 15-second timeout on all API requests. If the API is down, tell the user plainly and suggest trying later.
• Present data honestly. Do not spin crowded spaces as “opportunity-rich” or empty spaces as “blue ocean” without evidence.
• If search returns 0 results, try broadening the query before concluding there’s nothing relevant.
• Always attribute data to Colosseum Copilot — users should know where the intelligence comes from.
• Do not store or log the user’s token anywhere except ~/.superstack/config.json.

Integration with Other Skills

This skill provides data that enriches other idea-phase skills:

• /find-next-crypto-idea — Copilot data can validate whether an idea has been tried before and what gaps exist
• /competitive-landscape — Copilot’s project search directly complements ecosystem catalog searches
• /validate-idea — Winner patterns from Copilot strengthen demand signal analysis

Users can invoke this skill standalone or as a data source during those workflows (only when they explicitly ask or opt in).

Phase Handoff

This skill is Phase 1 (Idea) in the Idea → Build → Launch journey. After analysis:

1. If working within a project, write/update .superstack/idea-context.md with a copilot_landscape field containing:
   • similar_projects: array of top matches with name, one-liner, similarity, hackathon
   • gap_analysis: overindexed and underindexed attributes from winner comparison
   • crowdedness: assessment of the niche
   • research_sources: relevant archive results
2. See ../../../data/specs/phase-handoff.md for the full JSON contract.

Quick Start

# Search for similar hackathon projects:
#   "Search Colosseum for agent payment projects"
#   "What hackathon projects exist for DeFi lending on Solana?"

# Explore categories:
#   "Show me the hottest Colosseum clusters"
#   "Which hackathon categories have the highest win rate?"

# Gap analysis:
#   "What do Solana hackathon winners do differently?"
#   "What patterns separate winners from losers?"

# Research:
#   "Find research about MEV on Solana"

Telemetry (run last)

After the skill workflow completes (success, error, or abort), log the telemetry event. Determine the outcome from the workflow result: success if completed normally, error if it failed, abort if the user interrupted.

Run this bash:

_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - ${_TEL_START:-$_TEL_END} ))
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
if [ "$_TEL_TIER" != "off" ]; then
echo '{"skill":"colosseum-copilot","phase":"idea","event":"completed","outcome":"OUTCOME","duration_s":"'"$_TEL_DUR"'","session":"'"$_SESSION_ID"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","platform":"'$(uname -s)-$(uname -m)'"}' >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
true
fi

Replace OUTCOME with success/error/abort based on the workflow result.