Skip to content

Smart Artifact Discovery Guide

This guide explains how to use SkillMeat's Smart Import & Discovery feature to find and import artifacts from your local projects, directories, and external sources.

Table of Contents

What is Artifact Discovery

Artifact discovery is a feature that automatically scans your local directories (particularly .claude/ project directories) to find Claude Code artifacts like skills, commands, agents, and MCP servers. This saves time by automatically detecting existing artifacts that can be imported into your SkillMeat collection.

Supported Artifact Types

The discovery system automatically detects:

  • Skills - Identified by SKILL.md file
  • Commands - Identified by COMMAND.md or command.md file
  • Agents - Identified by AGENT.md or agent.md file
  • Hooks - Identified by HOOK.md or hook.md file
  • MCP Servers - Identified by MCP.md or mcp.json file

Using the CLI discover Command

The skillmeat discover command lets you search for artifacts across your personal collection, the SkillMeat marketplace, and curated web sources directly from the command line.

Basic Usage

The simplest form provides an intent (a description of what you need) as a quoted string:

skillmeat discover "authentication middleware for FastAPI"

You can also read intent from a file:

skillmeat discover --file requirements.md

Command Output

When you run the command, you'll see a table with:

Column Meaning
Name Artifact name
Type Artifact type (skill, command, agent, hook, mcp, etc.)
Leg Source: collection (yours), marketplace (official), or web (GitHub)
Trust Tier Confidence level: trusted, candidate, unverified, or quarantined
Score Relevance score (0.0-1.0, higher is better)

Example output:

Artifact Discovery Results

Legs hit: collection, marketplace | Failed: web

Name                      Type       Leg        Trust Tier     Score
auth-middleware           skill      collection trusted        0.92
fastapi-auth            command    marketplace trusted        0.88
jwt-patterns            agent      web        unverified     0.65

The header shows which search sources succeeded and if any failed. The duration tells you how long the search took.

Understanding Trust Tiers

Each result has a trust tier that reflects its provenance:

  • TRUSTED (green) — From your personal collection or official marketplace
  • CANDIDATE (yellow) — From an allowlisted GitHub organization
  • UNVERIFIED (gray) — From external/community sources; requires confirmation before install
  • QUARANTINED (red) — Blocked sources; will not install

See Discovery Trust Tiers for detailed trust configuration.

Understanding Relevance Scores

The score blends four factors:

  • 50% — Keyword match strength
  • 20% — How recently updated
  • 20% — Popularity (install count)
  • 10% — Trust tier weight

Higher scores indicate better matches for your search. Scores >= 0.7 are typically excellent; >= 0.4 are reasonable; < 0.4 may require scrolling down or refining your search.

Using Agent Mode (Tier 3)

If agent mode is enabled in your setup, you can use the Agent tab on the discover page for advanced multi-turn search:

How It Works:

  1. Enter your search query (or a detailed description of what you need)
  2. The agent will iteratively refine its search strategy
  3. Watch the Thinking Panel to see the agent's reasoning and strategy adjustments
  4. Results are streamed in real-time as the agent completes each turn
  5. After 5 turns (or your configured limit), results are finalized

Thinking Panel:

When using Agent mode, you'll see a collapsible "Thinking" panel above the candidate list. This shows the agent's intermediate reasoning, which search strategy it's trying, and how it evaluates results. You can collapse it if you just want to see results.

Example Query (Agent Mode):

Instead of a short keyword query, agent mode handles conversational descriptions well:

I need a middleware that validates JWT tokens and extracts claims,
with support for RS256 signing. Should work in FastAPI.

The agent will: - Interpret your intent (JWT validation + FastAPI) - Search across collection, marketplace, and web - Evaluate candidates for token extraction capability - Return the most relevant matches

Cost & Latency:

  • Time: 5–15 seconds depending on search difficulty and max turns
  • Cost: ~$0.30–$0.50 per search (Claude Sonnet); higher with Opus or more turns

When to Use Agent Mode:

  • Searching for something you're not sure exists
  • Need very specific combinations of features
  • Descriptions are conversational rather than keyword-based
  • You have time for a thorough, iterative search

Command Options

Filter by Artifact Type

Limit results to specific artifact types using --types:

skillmeat discover "patterns" --types skill,command

Comma-separated list. Valid types: skill, command, agent, hook, mcp, workflow, composite, context_module, template, group, deployment_set, context_pack, bundle, project_config, spec_file, rule_file, context_file, progress_template.

Limit Number of Results

Control how many candidates are returned (1-100, default: 20):

skillmeat discover "testing" --max-results 10

Install Candidates

Prompt interactively to install candidates:

skillmeat discover "rate limiting" --install

For each candidate, you'll be prompted:

Install rate-limiting-middleware? [y/N]:

Candidates with unverified or quarantined trust tiers always require explicit confirmation, even with --yes.

Non-Interactive Install

Auto-confirm all prompts (except for unverified/quarantined sources):

skillmeat discover "auth patterns" --install --yes

Generate Bundle Manifest Fragment

Output a TOML snippet ready to paste into manifest.toml:

skillmeat discover "utilities" --bundle

This emits results in a table, then prints a manifest fragment like:

# manifest.toml fragment:
[[artifacts]]
name = "string-utils"
type = "skill"
source = "anthropics/skills/string-utils"
version = "latest"
scope = "user"

Practical Examples

Search for authentication-related skills:

skillmeat discover "JWT token validation"

This returns top 20 matches ranked by relevance and trust. Trusted/candidate tiers float to the top.

Example 2: Narrow Search by Type and Install

Find command-line tools, with install prompts:

skillmeat discover --file tools-needed.md --types command --max-results 5 --install

Example 3: Batch Installation from Requirements File

Create NEEDS.md:

# Project Requirements

We need middleware for:
- Request rate limiting
- CORS handling
- Request validation

Then discover and install interactively:

skillmeat discover --file NEEDS.md --install

You'll be prompted for each relevant candidate in turn.

Example 4: Export Manifest Fragment

Search for utilities and generate a manifest snippet to add to your project's manifest.toml:

skillmeat discover "string manipulation" --bundle --max-results 5 > utils-candidates.txt

Review the fragment, then copy it into your manifest.

Error Handling

Connection Error: If you see "Cannot connect to SkillMeat API":

skillmeat web dev --api-only  # Start the API in another terminal

Validation Error: If input validation fails (e.g., max-results out of range):

# max-results must be 1-100
skillmeat discover "test" --max-results 150  # ❌ Error: 150 out of range
skillmeat discover "test" --max-results 50   # ✅ OK

No Results: If no candidates are found, try:

  • Use broader keywords
  • Increase --max-results
  • Remove strict --types filters
  • Check your trust tier configuration (blocked sources won't show)

How Discovery Works

Automatic Scanning

When you navigate to the Manage page in SkillMeat's web interface, the system automatically:

  1. Scans directories - Recursively scans your configured project paths and the .claude/artifacts/ directory
  2. Detects artifacts - Identifies artifact types based on metadata files (SKILL.md, COMMAND.md, etc.)
  3. Extracts metadata - Reads YAML frontmatter from each artifact to get name, description, tags, and source information
  4. Validates structure - Verifies that each discovered artifact has the required files
  5. Compiles results - Returns a list of discoverable artifacts with any errors encountered

Scan Performance

The discovery system is optimized for speed:

  • Fast scanning - Typical scans of 50+ artifacts complete in under 2 seconds
  • Graceful error handling - Individual artifact errors don't prevent scanning other artifacts
  • Efficient detection - Uses optimized file system operations to minimize I/O

Metadata Extraction

For each discovered artifact, the system extracts:

Field Source Description
Name YAML frontmatter or directory name Artifact identifier
Type Metadata file type skill, command, agent, hook, mcp
Description YAML frontmatter What the artifact does
Tags YAML frontmatter Categories and keywords
Source YAML frontmatter Original GitHub source (if available)
Version YAML frontmatter Version identifier (if available)
Scope Inferred user (global) or local (project-specific)

Using the Bulk Import Modal

Opening the Discovery Modal

  1. Navigate to the Manage page in SkillMeat
  2. Click the Discover Artifacts or Import button
  3. The system automatically scans and displays discovered artifacts

The bulk import modal shows:

  • Artifact List - All discovered artifacts with type badges
  • Metadata Preview - Name, description, tags for each artifact
  • Selection Checkbox - Toggle artifacts for import
  • Results Summary - Count of artifacts found and errors
  • Import Button - Perform the bulk import operation

Understanding the Results

Artifacts Found

The modal displays each discovered artifact with:

  • Icon indicating artifact type (skill, command, agent, etc.)
  • Artifact name and full path
  • Brief description (from frontmatter)
  • Tags (if available)
  • Status indicator (ready to import, conflict, error)

Errors Section

If errors occurred during discovery, they're listed with:

  • Error message describing the problem
  • Artifact path (if applicable)
  • Suggested resolution

Common errors:

Error Cause Resolution
"Could not detect artifact type" Missing metadata file Add SKILL.md, COMMAND.md, etc.
"Invalid artifact structure" Missing required files Ensure artifact has proper structure
"Failed to parse frontmatter" Invalid YAML syntax Fix YAML in metadata file
"Permission denied" Access restrictions Check file permissions

Selecting and Importing Artifacts

Step-by-Step Import

  1. Review artifacts - Scan through the discovered list
  2. Select artifacts - Check the boxes next to artifacts you want to import
  3. Preview changes - Review metadata that will be imported
  4. Click Import - Execute the bulk import operation
  5. Check results - View the per-artifact import status

Batch Import

You can import multiple artifacts at once:

  • Select multiple artifacts using checkboxes
  • The system tracks which ones have conflicts
  • Import succeeds for all non-conflicting artifacts
  • Failed artifacts show specific error reasons

Import Status

After import, each artifact shows a status:

  • Success - Artifact imported to collection
  • Conflict - Artifact already exists (if auto-resolve is disabled)
  • Error - Import failed with specific error message
  • Skipped - User deselected or manually skipped

Editing Parameters Before Import

Modifying Artifact Metadata

Before importing, you can edit:

  • Name - Change artifact identifier
  • Description - Override or add description
  • Tags - Add or modify categories
  • Scope - Choose user (global) or local (project-specific)
  • Version - Specify version if not auto-detected

When to Edit

Edit parameters when:

  • Auto-detection incomplete - Missing description or tags
  • Naming conflict - Need different name than detected
  • Scope adjustment - Want to change between user/local scope
  • Metadata override - Have updated information

Making Changes

  1. Click on an artifact - Opens the parameter editor
  2. Modify fields - Edit name, description, tags, scope
  3. Save changes - Changes apply only to the import operation
  4. Continue - Return to import modal

Default Values

If a field is empty or not detected:

  • Name - Derived from directory or file name
  • Description - Left empty (can add during import)
  • Tags - Empty list
  • Scope - Defaults to "user" (global scope)
  • Version - Defaults to "latest"

Discovery Modes (Three-Tier System)

SkillMeat's discovery system offers three modes, each with different latency and quality tradeoffs:

Tier 1: Quick Mode (Heuristic)

Default mode. Uses keyword matching and deterministic ranking across all search legs (collection, marketplace, web).

  • Latency: ~100ms
  • Quality: Keyword-based; works well for exact or near-exact matches
  • Cost: Free (no LLM API calls)
  • Best for: Fast searches, CI/CD pipelines, resource-constrained environments
  • CLI: skillmeat discover "query" (default)
  • Web: Select Quick tab on discover page

Tier 2: Enhanced Mode (LLM Enrichment + Reranking)

Augments Quick mode with LLM-powered intent enrichment and result reranking. Your search query is processed by an AI model to better understand your intent, and top results are reranked for improved relevance.

  • Latency: 1–2 seconds
  • Quality: Improved relevance on fuzzy or conversational queries
  • Cost: ~$0.01 per search (depends on LLM provider)
  • Requires: LLM provider configured (Claude, OpenAI, or Ollama)
  • Best for: Complex or conversational searches, users comfortable with API costs
  • CLI: skillmeat discover "query" --mode enhanced
  • Web: Select Enhanced tab on discover page

Tier 3: Agent Mode (Multi-Turn Agentic Loop)

Advanced mode using Claude Agent SDK for multi-turn reasoning. The agent can refine searches iteratively across all legs (collection, marketplace, web) and evaluate candidates to find the best matches.

  • Latency: 5–15 seconds (for 5-turn limit)
  • Quality: Best; agent adapts strategy based on intermediate results
  • Cost: ~$0.30–$0.50 per search (Sonnet); ~$1.50–$2.50 (Opus)
  • Requires: Claude API access (subscription OAuth or API key)
  • Best for: Hard-to-find artifacts, research-mode discovery, one-off specialized searches
  • CLI: skillmeat discover "query" --mode agent
  • Web: Select Agent tab on discover page (when enabled)

Configuration

Discovery behavior is controlled by environment variables that can be set in your shell or in SkillMeat's configuration.

Feature Flags

SKILLMEAT_DISCOVERY_WEB_ENABLED

  • Default: true
  • Purpose: Enables the web search leg (GitHub and other public sources) in discovery
  • When to disable: If you only want to search your collection and marketplace, set to false

SKILLMEAT_DISCOVERY_SSE_ENABLED

  • Default: true
  • Purpose: Enables streaming (Server-Sent Events) for real-time result delivery in the web UI
  • When to disable: For environments without SSE support or if you prefer buffered results; set to false to get all results at once after search completes

SKILLMEAT_DISCOVERY_LOG_ENABLED

  • Default: true
  • Purpose: Enables discovery audit logging to track searches and installations
  • When to disable: In privacy-sensitive environments, set to false to prevent logging

Agent Mode Configuration (Tier 3)

Enable Agent Mode Backend:

export SKILLMEAT_DISCOVERY_AGENT_ENABLED=true
export ANTHROPIC_API_KEY=sk-ant-...  # or CLAUDE_CODE_OAUTH_TOKEN

Enable Agent Mode in Web UI:

export NEXT_PUBLIC_SKILLMEAT_DISCOVERY_AGENT_ENABLED=true

⚠️ Important: The NEXT_PUBLIC_ prefix is required for Next.js. Without it, the Agent tab will not appear in the web UI even if the backend is enabled. Both environment variables must be set:

  1. Backend (SKILLMEAT_DISCOVERY_AGENT_ENABLED=true) — enables the Agent API
  2. Frontend (NEXT_PUBLIC_SKILLMEAT_DISCOVERY_AGENT_ENABLED=true) — shows Agent tab in UI

Tune Agent Iterations:

export SKILLMEAT_DISCOVERY_AGENT_MAX_TURNS=5  # default 5, max 10

Increasing max turns gives the agent more iterations to refine searches, but increases latency and cost. Default (5) is recommended.

Enhanced Mode Configuration (Tier 2)

Enable Enhanced Mode:

export SKILLMEAT_DISCOVERY_LLM_PROVIDER=claude   # or openai, ollama
export ANTHROPIC_API_KEY=sk-ant-...             # or OPENAI_API_KEY, etc.

Control Reranking:

export SKILLMEAT_DISCOVERY_LLM_RERANK_ENABLED=true  # default true

Set to false to use LLM enrichment only (skip reranking step).

Full LLM Provider Setup:

See Discovery Provider Setup for complete configuration of Claude, OpenAI, and Ollama providers, including subscription OAuth, API key priority resolution, and troubleshooting.

Advanced Configuration

Auto-Discovery on Import:

By default, discovery is manual. To automatically scan for local artifacts on collection import:

export SKILLMEAT_ENABLE_AUTO_DISCOVERY=true

Cache Settings:

export SKILLMEAT_DISCOVERY_CACHE_TTL=3600  # cache TTL in seconds (default: 3600)

Setting Configuration

Option 1: Environment Variables (Temporary)

For current session only:

export SKILLMEAT_DISCOVERY_WEB_ENABLED=false
skillmeat discover "authentication"

Option 2: Shell Profile (Persistent)

Add to ~/.bashrc or ~/.zshrc:

export SKILLMEAT_DISCOVERY_WEB_ENABLED=true
export SKILLMEAT_DISCOVERY_SSE_ENABLED=true
export SKILLMEAT_DISCOVERY_LOG_ENABLED=true

Then reload your shell:

source ~/.bashrc  # or ~/.zshrc

Option 3: Web Server Configuration

When starting the web server, pass as environment variables:

SKILLMEAT_DISCOVERY_WEB_ENABLED=false skillmeat web dev

Troubleshooting

Agent Mode Tab Not Appearing in Web UI

Problem: Backend has agent mode enabled, but the Agent tab doesn't appear in the discover page mode selector.

Root Cause: The frontend requires NEXT_PUBLIC_SKILLMEAT_DISCOVERY_AGENT_ENABLED=true. This prefix is required for Next.js to embed the flag in the browser-accessible bundle. Without the NEXT_PUBLIC_ prefix, the frontend cannot read the configuration.

Solution:

  1. Verify backend is enabled: 

    echo $SKILLMEAT_DISCOVERY_AGENT_ENABLED  # Should print: true

  2. Set frontend flag with NEXT_PUBLIC_ prefix: 

    export NEXT_PUBLIC_SKILLMEAT_DISCOVERY_AGENT_ENABLED=true

  3. If using .env.local: Add this line: 

    NEXT_PUBLIC_SKILLMEAT_DISCOVERY_AGENT_ENABLED=true

  4. Rebuild or restart dev server: 

    # For production build
pnpm build && pnpm start

# For dev server (auto-reloads on .env change)
pnpm dev

Why the NEXT_PUBLIC_ prefix? Next.js only exposes environment variables starting with NEXT_PUBLIC_ to the browser. Variables without this prefix are server-only and inaccessible to frontend code. See Next.js Environment Variables docs.

Artifacts Not Found

Problem: Discovery modal shows "0 artifacts found"

Causes and Solutions:

  1. Artifacts directory doesn't exist
  2. Create ~/.skillmeat/collection/artifacts/ directory

  3. Or configure custom artifacts path

  4. Missing metadata files

  5. Artifacts need SKILL.md, COMMAND.md, etc.

  6. Add required metadata file to your artifact

  7. Wrong directory path

  8. Check that artifacts are in the correct location

  9. Use "Scan Path" option to specify custom directory

  10. Artifacts are hidden

  11. Discovery skips files/dirs starting with "."
  12. Rename _skill to skill (remove leading underscore/dot)

Resolution Steps:

# Check if artifacts directory exists
ls -la ~/.skillmeat/collection/artifacts/

# Look for SKILL.md in your artifact
ls -la ~/.skillmeat/collection/artifacts/skills/my-skill/

# Verify frontmatter is valid YAML
head -20 ~/.skillmeat/collection/artifacts/skills/my-skill/SKILL.md

Partial Discovery Results

Problem: Some artifacts found, but not all expected ones

Causes and Solutions:

  1. Frontmatter parsing errors
  2. YAML syntax error in metadata file

  3. Check error messages in modal for specific artifacts

  4. Missing artifact type directory

  5. Artifact is in wrong directory structure

  6. Move artifacts to artifacts/skills/, artifacts/commands/, etc.

  7. Permission issues

  8. Some directories may not be readable
  9. Check file permissions with ls -la

Resolution Steps:

# Validate YAML syntax
python3 -c "import yaml; yaml.safe_load(open('SKILL.md'))"

# Check permissions
chmod -R 755 ~/.skillmeat/collection/artifacts/

# Review error details in import modal

Import Failures

Problem: Import modal appears but import fails

Causes and Solutions:

  1. Artifact already exists
  2. Enable "auto-resolve conflicts" option to overwrite

  3. Or delete existing artifact first

  4. Validation errors

  5. Required fields missing or invalid

  6. Check artifact metadata and edit before import

  7. Storage issues

  8. Insufficient disk space
  9. File system permissions problems

Resolution Steps:

# Check available disk space
df -h ~/.skillmeat/collection/

# Fix permissions
chmod -R u+w ~/.skillmeat/collection/artifacts/

# Check for existing artifacts with same name
skillmeat list | grep artifact-name

Scan Takes Too Long

Problem: Discovery scan is slow or times out

Causes and Solutions:

  1. Large number of artifacts
  2. Expected for 100+ artifacts

  3. Normal performance is 2 seconds for 50 artifacts

  4. Slow file system

  5. Network drives or external storage

  6. Move artifacts to local drive if possible

  7. System load

  8. Other processes consuming resources
  9. Wait for other tasks to complete

Performance Tips:

  • Keep artifacts on local SSD if possible
  • Limit to 50-100 artifacts per collection
  • Use custom scan path to narrow search

Metadata Not Populated

Problem: Description, tags, or other fields are empty after import

Causes and Solutions:

  1. Frontmatter not in metadata file
  2. Add YAML frontmatter to SKILL.md, COMMAND.md, etc.

  3. Follow format: ---\nkey: value\n---

  4. Invalid YAML syntax

  5. Check for indentation and quotes

  6. Use YAML validator tool

  7. Field names not recognized

  8. Use standard fields: name, description, tags, author
  9. Check artifact documentation for exact field names

Add Metadata Example:

---
name: My Skill
description: What this skill does
tags: [design, automation, useful]
author: John Doe
version: 1.0.0
---

# Skill content...

Best Practices

Before Discovering Artifacts

  1. Organize artifact structure
  2. Use consistent directory names (skills, commands, agents)

  3. Place artifacts in .claude/artifacts/ or configured path

  4. Complete metadata

  5. Add comprehensive YAML frontmatter to each artifact

  6. Include name, description, tags, and author

  7. Use clear naming

  8. Artifact names should be descriptive and unique

  9. Use kebab-case: my-skill, useful-command

  10. Validate YAML

  11. Ensure frontmatter is syntactically correct
  12. Test with YAML validator before discovering

During Import

  1. Review carefully
  2. Check each artifact's metadata before import

  3. Verify descriptions and tags are accurate

  4. Resolve conflicts

  5. Decide on auto-resolve or manual handling

  6. Review existing artifacts to avoid duplication

  7. Use descriptive tags

  8. Add meaningful tags for organization

  9. Use 3-5 tags per artifact (not too many)

  10. Note source location

  11. Keep track of where artifacts came from
  12. Useful for tracking updates and versions

After Import

  1. Verify imports
  2. Check import status in the results modal

  3. Review newly imported artifacts in collection

  4. Update if needed

  5. Edit artifact metadata if needed after import

  6. Update parameters and relationships

  7. Test artifacts

  8. Run imported artifacts to verify they work

  9. Check for any missing dependencies

  10. Deploy to projects

  11. Use imported artifacts in your projects
  12. Deploy from collection to .claude/ directories

Performance Optimization

  1. Limit scan scope
  2. Use custom scan path to scan specific directories

  3. Avoid scanning entire home directory

  4. Clean up artifacts

  5. Delete unused or duplicate artifacts

  6. Keep collection size reasonable

  7. Organize by type

  8. Separate skills, commands, agents into subdirectories

  9. Improves discovery performance

  10. Use version numbers

  11. Track artifact versions in metadata
  12. Easier to manage updates and deployments