Artifact Discovery

SkillMeat's artifact discovery system helps you find and import Claude Code artifacts from your personal collection, the marketplace, and the web. It offers three tiers of searching—from fast keyword-based search to advanced AI-powered discovery.

Overview

Discovery works by searching across three legs (data sources):

Leg	Source	Content	Search Method
Collection	Local artifacts	Your personal SkillMeat collection	Local filesystem
Marketplace	Curated sources	Anthropic-vetted skills, commands, agents	Marketplace catalog
Web	Public sources	Popular awesome-lists and GitHub topics	Web indexing

Each leg is searched in parallel, results are ranked by relevance, and you get a unified list of candidates—all without needing AI integration if you don't want it.

Discovery Modes

SkillMeat supports three discovery modes, each building on the previous:

Quick Mode (Default)

Fast, deterministic keyword search. No LLM required.

How it works: 1. Extracts keywords and artifact type hints from your query 2. Searches all three legs (collection, marketplace, web) in parallel 3. Ranks results by keyword matching and metadata relevance 4. Returns ranked candidates in seconds

Best for: Quick searches, no API costs, offline-friendly

Usage:

# CLI (default)
skillmeat discover "canvas drawing skill"

# API
curl -X POST http://localhost:8080/api/v1/discover \
  -H "Content-Type: application/json" \
  -d '{
    "text": "canvas drawing skill",
    "mode": "quick"
  }'

Response:

{
  "candidates": [
    {
      "source": "marketplace",
      "name": "canvas-design",
      "artifact_type": "skill",
      "url": "https://github.com/anthropics/skills/tree/main/canvas-design",
      "trust_tier": "trusted",
      "score": 0.92,
      "metadata": {
        "description": "Draw diagrams and visual art in Claude documents",
        "install_count": 1200
      }
    }
  ],
  "legs_hit": ["collection", "marketplace", "web"],
  "legs_failed": [],
  "duration_ms": 245
}

Enhanced Mode

Adds optional LLM enrichment for better understanding of your intent, and optional reranking for improved relevance.

How it works: 1. Uses LLM to enrich your query with additional keywords and artifact type hints 2. Searches all three legs with enriched intent 3. Optionally reranks results using LLM judgment (requires feature flag) 4. Returns more semantically relevant results

Requirements: - LLM provider configured (Claude, OpenAI, or Ollama) - API credentials for the provider

Best for: Complex searches, semantic understanding, higher relevance

Usage:

# CLI
skillmeat discover "I need a skill for drawing in documents" --mode enhanced

# API with enhanced mode
curl -X POST http://localhost:8080/api/v1/discover \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I need a skill for drawing in documents",
    "mode": "enhanced"
  }'

LLM Cost: ~10-50 tokens per enrichment, minimal additional cost

Agent Mode

Multi-turn agentic discovery using Claude to guide the search interactively.

How it works: 1. Claude Agent SDK processes your query 2. Agent iteratively refines search and explores multiple angles 3. Performs up to 6 turns (configurable) of searching and reasoning 4. Returns deeply relevant, thoughtfully-curated candidates

Requirements: - SkillMeat with pip install skillmeat[agent] (includes anthropic package) - Claude API key or Subscription OAuth token - Feature flag: SKILLMEAT_DISCOVERY_AGENT_ENABLED=true

Best for: Complex, exploratory searches; understanding unfamiliar artifact types; research

Usage:

# CLI (requires installation)
skillmeat discover "I want to create a workflow that integrates with GitHub and notifies Slack" --mode agent

# API
curl -X POST http://localhost:8080/api/v1/discover \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I want to create a workflow that integrates with GitHub and notifies Slack",
    "mode": "agent",
    "max_results": 10
  }'

Streaming Support: Agent mode supports Server-Sent Events (SSE) for real-time reasoning display:

curl -X POST http://localhost:8080/api/v1/discover \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "workflow for GitHub integration",
    "mode": "agent"
  }'

Events emitted: - thinking — agent reasoning per turn - candidate — ranked result as it's finalized - done — final result set with summary - error — discovery failure

Configuration

Environment Variables

Variable	Description	Required For	Default	Example
SKILLMEAT_DISCOVERY_LLM_PROVIDER	LLM provider (claude, openai, ollama)	Enhanced, Agent	claude	claude
SKILLMEAT_DISCOVERY_LLM_MODEL	Override provider's default model	Enhanced, Agent (optional)	provider default	claude-sonnet-4-6
SKILLMEAT_DISCOVERY_AGENT_ENABLED	Enable agent mode (Tier 3)	Agent only	false	true
SKILLMEAT_DISCOVERY_AGENT_MAX_TURNS	Max agent reasoning turns (1-10, capped at 10)	Agent (optional)	5	6
SKILLMEAT_DISCOVERY_LLM_RERANK_ENABLED	Enable LLM reranking in enhanced mode	Enhanced (optional)	true	false
SKILLMEAT_DISCOVERY_LLM_RERANK_MODEL	Override model for reranking only	Enhanced (optional)	inherits enricher model	claude-haiku-4-5
SKILLMEAT_DISCOVERY_WEB_ENABLED	Enable web search leg	All modes	true	false
SKILLMEAT_DISCOVERY_SSE_ENABLED	Enable Server-Sent Events (streaming)	Agent (optional)	true	false
SKILLMEAT_DISCOVERY_LOG_ENABLED	Log discovery requests to audit trail	All modes (optional)	true	false
SKILLMEAT_DISCOVERY_CACHE_TTL	Cache TTL in seconds	All modes (optional)	3600	1800
ANTHROPIC_API_KEY	Claude API key (direct auth)	Enhanced/Agent (auth)	none	sk-ant-...
CLAUDE_CODE_OAUTH_TOKEN	Subscription token (OAuth via keychain)	Agent (auth, recommended)	none	oauth token

Configuring LLM Provider

SkillMeat supports Claude (API key or OAuth subscription), OpenAI, and Ollama for discovery enrichment and agent mode.

Claude (Recommended)

Option 1: API Key (Direct)

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=claude
export SKILLMEAT_DISCOVERY_LLM_MODEL=claude-sonnet-4-6
export ANTHROPIC_API_KEY=sk-ant-...

Get your API key from console.anthropic.com.

Option 2: Subscription OAuth (Recommended for Agent Mode)

For agent mode, Claude OAuth subscription (via keychain) provides improved rate limits and cost efficiency:

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=claude
export SKILLMEAT_DISCOVERY_AGENT_ENABLED=true
# CLAUDE_CODE_OAUTH_TOKEN is auto-resolved from system keychain

To set up Claude subscription OAuth: 1. Ensure your Claude Code environment is configured with Claude subscription 2. Token is automatically read from the system keychain (no explicit export needed) 3. Verify: skillmeat discover "test" --mode agent should work without ANTHROPIC_API_KEY

If keychain token fails, falls back to ANTHROPIC_API_KEY if present.

OpenAI

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=openai
export SKILLMEAT_DISCOVERY_LLM_MODEL=gpt-4o
export OPENAI_API_KEY=sk-...

Ollama (Local / Self-Hosted)

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=ollama
export SKILLMEAT_DISCOVERY_LLM_MODEL=llama2
# Ollama defaults to http://localhost:11434
# Override with: export OLLAMA_BASE_URL=http://custom:11434

Verification

Test your configuration:

# Quick mode (no LLM required)
skillmeat discover "test query" --mode quick

# Enhanced mode (requires LLM)
skillmeat discover "test query" --mode enhanced

# Agent mode (requires LLM + agent_enabled flag)
export SKILLMEAT_DISCOVERY_AGENT_ENABLED=true
skillmeat discover "test query" --mode agent

Common errors: - ProviderError: provider 'claude' not found → Check SKILLMEAT_DISCOVERY_LLM_PROVIDER spelling - AuthenticationError → Verify API key / OAuth token is valid - RateLimitError (agent mode) → Consider reducing SKILLMEAT_DISCOVERY_AGENT_MAX_TURNS or using subscription OAuth

Enabling Agent Mode (Tier 3)

Agent mode requires the Anthropic SDK and explicit enablement:

# Install with agent support
pip install skillmeat[agent]

# Or upgrade existing installation
pip install --upgrade skillmeat

# Enable agent mode
export SKILLMEAT_DISCOVERY_AGENT_ENABLED=true

# Configure LLM (if not using subscription OAuth)
export SKILLMEAT_DISCOVERY_LLM_PROVIDER=claude
export ANTHROPIC_API_KEY=sk-ant-...

# Test
skillmeat discover "find a workflow skill" --mode agent

Requirements: - Python 3.9+ - SkillMeat installed with [agent] extra (includes anthropic>=0.7.0) - Claude API key or subscription OAuth token (via keychain) - SKILLMEAT_DISCOVERY_AGENT_ENABLED=true environment variable

Tuning: - SKILLMEAT_DISCOVERY_AGENT_MAX_TURNS (1-10, default 5) — Higher = more thorough but higher cost - For cost-conscious usage: set to 3-4 turns - For complex queries: 5-6 turns recommended

API Reference

POST /api/v1/discover

Discover artifacts across collection, marketplace, and web.

Request:

Field	Type	Description	Example
text	string (optional)	Free-text query	"canvas drawing skill"
file_path	string (optional)	Path to a file for context	"/project/CLAUDE.md"
artifact_types	array (optional)	Restrict to these types	["skill", "command"]
max_results	integer (default 20)	Max candidates to return (1-100)	20
mode	string (default "quick")	Discovery mode: quick, enhanced, agent	"quick"

At least one of text or file_path must be provided.

Response:

Field	Type	Description
candidates	array	Ranked discovery candidates
legs_hit	array	Search legs that succeeded (collection, marketplace, web)
legs_failed	array	Search legs that failed or timed out
duration_ms	integer	Total search time in milliseconds
mode	string	Mode used: quick, enhanced, agent
llm_tokens_in	integer	Total input tokens (LLM modes only)
llm_tokens_out	integer	Total output tokens (LLM modes only)
agent_turns	integer	Number of agent iterations (agent mode only)

Candidate Fields:

Field	Type	Description
source	string	Where it came from: collection, marketplace, web
name	string	Artifact name
artifact_type	string	Type: skill, command, agent, hook, mcp, etc.
url	string	Source URL if available
trust_tier	string	trusted, candidate, unverified, or quarantined
score	float	Ranking score (0.0–1.0)
metadata	object	Additional metadata (description, install_count, etc.)

Example:

curl -X POST http://localhost:8080/api/v1/discover \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "text": "workflow skill for automating repetitive tasks",
    "artifact_types": ["skill", "workflow"],
    "max_results": 15,
    "mode": "enhanced"
  }' | jq .

GET /api/v1/discover/log

Retrieve paginated audit log of past discovery requests.

Query Parameters:

Parameter	Type	Description	Default
cursor	string	Pagination cursor from previous page	(start from newest)
limit	integer	Results per page (1-100)	10

Response:

{
  "items": [
    {
      "id": 42,
      "input_text": "canvas drawing skill",
      "input_file_path": null,
      "candidate_count": 15,
      "legs_hit": ["collection", "marketplace"],
      "legs_failed": [],
      "duration_ms": 312,
      "created_at": "2026-04-24T14:32:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6IDQxfQ=="
}

POST /api/v1/discover/refresh-index

Refresh the curated web search index. Useful after updating awesome-list configurations.

No request body required.

Response:

{
  "status": "completed",
  "sources_refreshed": 3,
  "errors": []
}

MCP Tool Registration

SkillMeat exposes discovery as an MCP tool for integration with other Claude Code tools and integrations.

skillmeat-mcp Server

The skillmeat-mcp MCP server provides the discover_artifacts tool:

Tool: discover_artifacts

Parameter	Type	Description	Example
text	string	Free-text search query	"canvas drawing skill"
mode	string (optional)	quick, enhanced, or agent	"enhanced"
artifact_types	array (optional)	Filter by type	["skill", "command"]
max_results	integer (optional, default 20)	Limit results (1-100)	10

Response:

{
  "candidates": [
    {
      "name": "canvas-design",
      "type": "skill",
      "source": "marketplace",
      "score": 0.94,
      "description": "Draw diagrams and visual art",
      "url": "https://github.com/anthropics/skills/tree/main/canvas-design"
    }
  ],
  "total": 15,
  "mode_used": "enhanced",
  "duration_ms": 1200
}

Registering the MCP Server

Add to your claude.json or environment configuration:

{
  "mcp_servers": {
    "skillmeat": {
      "command": "skillmeat-mcp",
      "args": ["--mode", "sse"],
      "env": {
        "SKILLMEAT_API_URL": "http://localhost:8080",
        "SKILLMEAT_DISCOVERY_MODE": "enhanced"
      }
    }
  }
}

Or via environment:

export SKILLMEAT_MCP_ENABLED=true
export SKILLMEAT_MCP_MODE=sse
export SKILLMEAT_API_URL=http://localhost:8080

The discover_artifacts tool then becomes available to Claude Code and other MCP-compatible tools in your project.

Degradation & Fallback Behavior

SkillMeat discovery is designed to degrade gracefully when LLM providers or search legs become unavailable.

Rate Limit Degradation

When LLM provider rate limits are exceeded (429 errors):

• Enhanced mode: Falls back to heuristic reranking (Quick mode results)
• Agent mode: Stops agent reasoning and returns best candidates found so far
• All modes: mode_degraded flag set to true in response

Response with degradation:

{
  "candidates": [...],
  "mode_requested": "enhanced",
  "mode_used": "quick",
  "mode_degraded": true,
  "degradation_reason": "LLM provider rate limited (429)",
  "duration_ms": 445,
  "warning": "Results ranked heuristically; LLM enrichment skipped"
}

SSE Streaming with Degradation

For agent mode with SSE, a degradation event is emitted when rate limits trigger:

curl -N -X POST http://localhost:8080/api/v1/discover \
  -H "Accept: text/event-stream" \
  -d '{"text":"...","mode":"agent"}'

Event stream:

event: thinking
data: {"turn":1,"reasoning":"Searching..."}

event: degradation
data: {"reason":"LLM rate limited","new_mode":"quick","candidates_so_far":8}

event: done
data: {"candidates":[...],"mode_used":"quick","mode_degraded":true}

Search Leg Failures

When individual search legs timeout or fail:

• Collection leg fails: Cannot search local collection (filesystem may be inaccessible)
• Marketplace leg fails: Official marketplace is unreachable
• Web leg fails: Awesome-list indexing is slow (most common; 5-second timeout)

Behavior: - Non-fatal; partial results returned with legs_failed list - Only report as error if all legs fail - Web leg timeout is common and does not degrade mode

Example response with partial failure:

{
  "candidates": [...],
  "legs_hit": ["collection", "marketplace"],
  "legs_failed": ["web"],
  "legs_failed_reasons": ["web: timeout (5s)"],
  "mode_degraded": false,
  "warning": "Web search timed out; results from local sources only"
}

Graceful Fallback

When agent mode becomes unavailable:

1. Feature disabled: Returns 400 with explanation

   {
     "error": "Agent mode not available",
     "detail": "SKILLMEAT_DISCOVERY_AGENT_ENABLED=false; use enhanced or quick mode"
   }
   

2. LLM provider unreachable: Returns 503 (service unavailable)

   {
     "error": "LLM provider unreachable",
     "detail": "Claude API is currently unavailable. Try quick mode.",
     "retry_after": 60
   }
   

3. Agent package missing: Returns 400 with guidance

   {
     "error": "Agent mode requires anthropic package",
     "detail": "Install: pip install skillmeat[agent]"
   }
   

Disabling Degradation (Expert)

To reject degraded results and fail fast:

curl -X POST http://localhost:8080/api/v1/discover \
  -H "Content-Type: application/json" \
  -d '{
    "text": "...",
    "mode": "enhanced",
    "reject_degradation": true
  }'

If rate limited, returns 429 instead of degrading to heuristic mode.

Examples

Example 1: Quick Search for a Canvas Skill

# Simple, fast search
skillmeat discover "canvas"

# Or via API
curl -X POST http://localhost:8080/api/v1/discover \
  -H "Content-Type: application/json" \
  -d '{"text": "canvas", "mode": "quick"}'

Results return in <500ms. Perfect for quick lookups.

Example 2: Enhanced Search with Type Filtering

# Search for skills and commands related to PDF handling
skillmeat discover "pdf document processing" \
  --artifact-types skill,command \
  --mode enhanced

# API version
curl -X POST http://localhost:8080/api/v1/discover \
  -H "Content-Type: application/json" \
  -d '{
    "text": "pdf document processing",
    "artifact_types": ["skill", "command"],
    "mode": "enhanced"
  }'

LLM enrichment understands "pdf" and "document processing" are related, finding more relevant results.

Example 3: Context-Aware Agent Discovery

# Use project CLAUDE.md for context
skillmeat discover \
  --file-path /my/project/CLAUDE.md \
  --mode agent \
  --text "artifacts I need for this project"

The agent reads your project structure and architecture, then recommends tailored skills and commands.

Example 4: Streaming with SSE (Agent Mode)

# Watch agent reasoning in real-time
curl -X POST http://localhost:8080/api/v1/discover \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "multi-step workflow for deployment",
    "mode": "agent"
  }' | while read line; do echo "$line"; done

Output:

event: thinking
data: {"reasoning":"User wants workflow for deployment... could involve multiple artifact types","turn":1}

event: thinking
data: {"reasoning":"Searching for command artifacts for orchestration...","turn":2}

event: candidate
data: {"name":"workflow-executor","score":0.94,"source":"marketplace",...}

event: done
data: {"candidates":[...],"duration_ms":1245,...}

Example 5: Discovering Artifacts from Collection

# Search within personal collection
skillmeat discover "my custom canvas skill" --mode quick

If you have a local artifact named "canvas-custom", it will appear in results with source: collection.

Trust Tiers

Artifacts are classified by trust based on their provenance:

Tier	Description	Example
trusted	Verified sources (Anthropic official, highly-starred)	Anthropic's canvas-design
candidate	Community submissions, peer-reviewed	Popular GitHub repos
unverified	New or unvetted sources	First-time publishers
quarantined	Flagged as problematic (security, deprecated)	Broken or malicious artifacts

Always check the trust tier before importing unknown artifacts.

Performance Notes

Mode	Latency	Cost	Best For
Quick	200–500ms	None	Fast searches, offline
Enhanced	1–2s	~50 tokens	Better understanding
Agent	5–30s	~500–2000 tokens	Complex discovery

Latencies include: - Per-leg timeout: 5 seconds (web leg may be slowest) - LLM API roundtrip: 1–2 seconds - Agent reasoning: 0.5–1 second per turn

Troubleshooting

"Tier 3 agent mode requires the anthropic package"

Problem: Tried to use agent mode without installing the optional dependency.

Solution:

pip install skillmeat[agent]
export SKILLMEAT_DISCOVERY_AGENT_ENABLED=true

Discovery returns no results

Possible causes: 1. Query is too specific or uses uncommon keywords 2. Web leg is disabled (SKILLMEAT_DISCOVERY_WEB_ENABLED=false) 3. Marketplace is not configured 4. No artifacts in your collection match the query

Solutions: - Try a simpler query (e.g., "skill" instead of "advanced skill for cloud deployment") - Check which legs hit: "legs_hit": ["collection"] means marketplace/web are disabled - Use enhanced or agent mode for better semantic matching - Verify collection has artifacts: skillmeat list

LLM enrichment failed, falling back to heuristic

Problem: LLM provider is misconfigured or unreachable.

Solution: 1. Verify environment variables:

echo $ANTHROPIC_API_KEY
echo $SKILLMEAT_LLM_PROVIDER

2. Test the provider directly:

# For Claude
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-opus","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'

3. Check firewall/proxy settings

Legs failed (e.g., web leg timed out)

Problem: One or more search legs failed to complete within 5 seconds.

Solution: - This is non-fatal; partial results are still returned - Check legs_hit and legs_failed in response - Retry: legs occasionally timeout due to network issues - For web leg: run skillmeat discover --refresh-index to pre-warm cache

High LLM token usage

Problem: Enhanced or agent mode is consuming many tokens.

Solution: - For enhanced: results are still relevant; token usage is normal (~100 tokens per search) - For agent: reduce SKILLMEAT_AGENT_MAX_TURNS (default 6, try 3–4) - Switch to quick mode if budget is tight - Use file-based context only when necessary

Keyboard Shortcuts (CLI)

Coming in a future version: use ↑/↓ to navigate results, Enter to import.

FAQ

Q: Does discovery work offline?

A: Quick mode works fully offline (collection + local indexing). Enhanced and agent modes require network access to LLM providers.

Q: Can I use my own LLM (not Claude/OpenAI)?

A: Yes. Set SKILLMEAT_LLM_PROVIDER=ollama and point to your local Ollama instance (http://localhost:11434).

Q: How are artifacts ranked?

A: Deterministic ranking combines: - Keyword match quality - Artifact type relevance - Trust tier - Popularity (install count)

LLM reranking (enhanced mode only) adds semantic judgment.

Q: Are discovery requests logged?

A: Yes, by default. View the audit log at GET /api/v1/discover/log. Disable with SKILLMEAT_DISCOVERY_LOG_ENABLED=false.

Q: Can I narrow search to specific artifact types?

A: Yes, use --artifact-types skill,command (CLI) or "artifact_types": ["skill", "command"] (API).

Q: What's the difference between marketplace and web legs?

A: Marketplace = officially-curated Anthropic sources. Web = awesome-lists and GitHub topics. Web results are less verified but broader.

See Also

• Discovery Provider Configuration Guide — Detailed setup for Claude (API key & OAuth), OpenAI, and Ollama
• Discovery Trust Tiers — Understanding artifact provenance and trust
• Artifact Management — How to organize, deploy, and sync artifacts
• Marketplace Integration — Browsing and configuring marketplace sources
• SkillMeat CLI Reference — Full CLI command documentation
• Importing Artifacts — Importing discovered artifacts into your collection