Discovery Trust Tiers¶

The discovery system classifies all artifact candidates into trust tiers based on their source and origin. Trust tiers control visibility, ranking, and installation workflows — preventing silent installation of unverified sources while promoting trusted artifacts to the top of results.

Overview¶

When you search for artifacts to add to your collection or project, SkillMeat discovers candidates from three sources:

Collection — Your own personal artifact collection
Marketplace — Official SkillMeat marketplace
Web — GitHub repositories and other web sources

Each candidate is assigned a trust tier that reflects its provenance. Higher-trust sources rank better in search results and surface more readily; lower-trust sources require explicit confirmation before installation.

Why trust tiers matter:

Prevent supply-chain attacks — Unverified web sources cannot silently install into your projects
Improve search quality — Your own artifacts and marketplace entries rank higher by default
Operator control — You define which external sources (GitHub orgs, domains) are trustworthy
Transparency — Every candidate's trust tier is visible in the UI and API responses

Trust Tier Definitions¶

Tier	Meaning	Applies To	Ranking Weight	UI Badge
TRUSTED	Source is owned or curated by you	Collection, Marketplace	1.0 (100%)	Green checkmark ✓
CANDIDATE	Web source is on your allowlist	GitHub/Web with matching domain	0.75 (75%)	Blue info icon
UNVERIFIED	Source is external and not allowlisted	Unknown GitHub orgs, open web sources	0.4 (40%)	Gray question mark
QUARANTINED	Source is blocked by operator	Previously untrustworthy sources	0.0 (0%) — filtered out	Red warning icon

Trust Tier Scoring¶

Discovery results are ranked using a four-component formula:

Score = relevance    × 0.50    (keyword match strength)
       + recency      × 0.20    (how recently updated)
       + install_norm × 0.20    (popularity / install count)
       + trust_tier   × 0.10    (provenance weight)

Trust tier contribution: 10% of total rank. A TRUSTED artifact with moderate relevance will typically rank higher than an UNVERIFIED artifact with perfect keyword match.

Trust tier weights:

TRUSTED: 1.0 (maximum weight)
CANDIDATE: 0.75
UNVERIFIED: 0.4
QUARANTINED: 0.0 (excluded from results)

Configuration¶

Trust tier assignment is automatic based on source and policy. The only configuration option is the web allowlist — a list of domains whose GitHub repositories should be marked as CANDIDATE (rather than UNVERIFIED).

Default Behavior (No Configuration)¶

If you don't configure an allowlist:

TRUSTED ← Your collection + Marketplace
CANDIDATE ← (none — no allowlist)
UNVERIFIED ← All external web sources (GitHub, etc.)
QUARANTINED ← (operator-configured only)

Setting Up an Allowlist¶

Edit ~/.skillmeat/config.toml and add a discovery.web_allowlist section:

[discovery]
web_allowlist = [
    "github.com",
    "gitlab.com",
    "api.github.com"
]

Valid domain formats:

Bare hostnames only: github.com, internal-git.acme.com
Lowercase (auto-normalized): GITHUB.COM → github.com
Port numbers are NOT supported: use github.com, not github.com:443
Wildcards are NOT supported: use github.com, not *.github.com

Examples:

Example 1: Single Internal GitHub Server¶

If your organization runs a private GitHub Enterprise server at git.internal.acme.com:

[discovery]
web_allowlist = [
    "git.internal.acme.com"
]

Now artifacts discovered from https://git.internal.acme.com/acme-org/skill-foo will be tagged CANDIDATE and rank higher in results.

Example 2: Multiple Trusted Domains¶

To trust both your internal GitHub and public open-source registries:

[discovery]
web_allowlist = [
    "github.com",
    "gitlab.com",
    "git.internal.acme.com"
]

Example 3: Enterprise Federation¶

In an enterprise deployment, the federation server may auto-seed trusted partner organizations:

[discovery]
web_allowlist = [
    "github.com",
    "partner-git.vendor.com",
    "internal.github.enterprise.com"
]

Operator Workflows¶

Promoting a Web Source to Trusted¶

The allowlist is the only way to promote a web source from UNVERIFIED to CANDIDATE. There is no UI button or one-click action — you must edit the config.

Workflow:

Discover an artifact from an external GitHub org that you want to trust
Extract the hostname: e.g., https://github.com/anthropics/skills/canvas → github.com
Add the hostname to discovery.web_allowlist in ~/.skillmeat/config.toml
Restart the web server or API (config is loaded on startup)
Re-run the discovery search — the same artifact will now be CANDIDATE

Quarantining a Source¶

If you discover a source with malicious or low-quality artifacts, you can quarantine it. This is a manual operation reserved for operators — no API or UI flow exists yet.

Workflow (planned):

Identify the problematic source (GitHub org, domain)
Add it to a quarantine list in ~/.skillmeat/config.toml (future version)
Restart the API
All candidates from that source will be tagged QUARANTINED and filtered from results

For now: Remove the domain from the allowlist if you trust it, or leave it as UNVERIFIED and warn users during discovery.

Monitoring Trust Assignments¶

Check what trust tier a discovered artifact received:

Via API:

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/api/v1/discovery/search?q=canvas-design" | \
  jq '.candidates[] | {name, trust_tier, source, source_url}'

Via CLI (when available):

skillmeat discover canvas-design --show-trust

Real-World Scenarios¶

Scenario 1: Adding a Company's Internal GitHub Org¶

Your company uses GitHub Enterprise at github.acme.com and wants to internally publish reusable skills. You trust everything from github.acme.com/acme-public/.

Configuration:

[discovery]
web_allowlist = [
    "github.acme.com"
]

Result: All skills discovered from github.acme.com/acme-public/ will be tagged CANDIDATE (trust_tier_weight: 0.75) and rank higher than UNVERIFIED open-source alternatives.

Scenario 2: Discovering Unknown Public Packages¶

A colleague recommends a skill published on GitHub by an individual developer: https://github.com/janedoe/awesome-prompt-engineering.

Without configuration, this artifact is UNVERIFIED (weight: 0.4) and will rank lower than your own artifacts or marketplace entries. If you vet the developer's work and want to promote it:

[discovery]
web_allowlist = [
    "github.com"  # Trust all GitHub sources (broader)
]

Alternatively, you could trust only specific high-reputation domains:

[discovery]
web_allowlist = [
    "github.com/anthropics",  # Not supported — hostnames only
]

(Note: hostname allowlist does NOT support path-based filtering. If you trust github.com, you trust all artifacts from any GitHub user.)

Scenario 3: Avoiding Typosquatting Attacks¶

An attacker publishes a look-alike skill with a similar name on GitHub. The authentic version is in your collection; the fake is on GitHub.

Authentic (from your collection) → TRUSTED (1.0)
Fake (from GitHub, no allowlist) → UNVERIFIED (0.4)

The authentic version will rank 2.5x higher due to trust tier alone. Users will see the real version first.

Security Considerations¶

Hostname Validation¶

The allowlist parser validates all entries to prevent injection attacks:

Valid: github.com, git.internal.acme.com, api.example.co.uk
Invalid: github.com:443 (ports not allowed), *.github.com (wildcards not allowed), https://github.com (schemes not allowed)

Invalid entries are skipped with a warning; no parsing errors are raised.

Case-Insensitive Matching¶

Hostnames are normalized to lowercase. GITHUB.COM and github.com are treated identically.

URL Scheme Validation¶

Only http:// and https:// schemes are considered for allowlist matching. Other schemes (file://, git://, ssh://) default to UNVERIFIED to prevent URL-injection attacks.

Permissions & Scoping¶

Who can configure trust tiers?

Local Edition: The user (full control via config.toml)
Enterprise Edition: Operators with admin role (via API or configuration)

Scope:

Allowlist: Organization-level in Local Edition; tenant-level in Enterprise Edition
Quarantine: (reserved for future implementation)

Troubleshooting¶

An artifact I trust is still UNVERIFIED¶

Check:

Is the artifact from a web source (GitHub, etc.)? (Collection and Marketplace sources are always TRUSTED.)
Is the hostname in your allowlist? Run cat ~/.skillmeat/config.toml | grep -A 10 discovery
Did you restart the API after editing the config? Config is loaded at startup.

Fix:

# Edit config
nano ~/.skillmeat/config.toml

# Add the hostname to discovery.web_allowlist
# Then restart:
skillmeat web dev

Artifacts are not appearing in search results¶

Check if they've been quarantined:

Is the source in a quarantine list? (Rare — only if operator has blocked it.)
Are you searching with appropriate filters?

Debug: Check the legs_failed field in the discovery API response to see which search legs encountered errors.

Invalid entries in allowlist are being silently skipped¶

Log output:

WARNING discovery.web_allowlist: skipping invalid domain entry 'github.com:443'
WARNING discovery.web_allowlist: skipping invalid domain entry '*.github.com'

Fix: Edit the config and use bare hostnames only (no ports, schemes, wildcards, or paths).

API Reference¶

Discovery Search Response¶

Each candidate in the response includes a trust_tier field:

{
  "candidates": [
    {
      "id": "abc123",
      "name": "canvas-design",
      "artifact_type": "skill",
      "source": "web",
      "source_url": "https://github.com/anthropics/skills/canvas",
      "trust_tier": "candidate",
      "version": "v2.1.0",
      "relevance_score": 0.92,
      "install_count": 1540,
      "metadata": {}
    }
  ]
}

Configuration Schema¶

[discovery]
web_allowlist = ["domain1.com", "domain2.com"]

Type: Array of strings (bare hostnames) Default: Empty array (no web sources trusted; all marked UNVERIFIED) Scope: User-level (Local), Tenant-level (Enterprise)

Discovery CLI Commands — Search and install artifacts
Edition Feature Matrix — Differences between Local and Enterprise
API Reference — Programmatic discovery endpoints