heurist-network Heurist Skill Marketplace Admin
Full command reference and DB/API operations: see references/commands.md.
Required env vars (.env)
SKILLS_DATABASE_URL— PostgreSQL connection stringINTERNAL_API_KEY— Admin HTTP endpoint keyAI3_API_KEY— Autonomys Auto Drive storage keyGITHUB_TOKEN— (optional) GitHub API rate limits
Standard Workflow: Add a Skill End-to-End
# 1. Ingest from GitHub URL
uv run python -m mesh.skill_marketplace.scripts.ingest_skill \
--url https://raw.githubusercontent.com/OWNER/REPO/main/SKILL.md \
--slug my-skill \
--category Stocks \
--label analytics \
--risk-tier low \
--source-url https://github.com/OWNER/REPO \
--author '{"display_name": "Name", "github_username": "username"}'
# 2. Check it's in DB as draft
uv run python -m mesh.skill_marketplace.scripts.list_skills --status draft
# 3. Approve
uv run python -m mesh.skill_marketplace.scripts.approve_skill --slug my-skill
# 4. Confirm live
uv run python -m mesh.skill_marketplace.scripts.list_skills --status verified
Key Ingest Flags
| Flag | Purpose |
|---|---|
--label analytics |
Repeatable secondary label; use for overlapping capability/domain metadata |
--source-path skills/my-skill |
Subfolder in multi-skill repos |
--external-api-dependency Name |
Repeat for each external API (e.g. CoinGecko) |
--reference-url URL |
Repeat for admin-only recordkeeping links (announcement tweet, project site, docs) |
--requires-secrets |
Skill needs API tokens/env vars |
--requires-private-keys |
Skill accesses private keys |
--requires-exchange-api-keys |
Needs exchange credentials |
--can-sign-transactions |
Skill signs on-chain txs |
--uses-leverage |
Leveraged trading |
--accesses-user-portfolio |
Reads user portfolio data |
--update |
Update existing skill in place (preserves id, download_count, star_count, created_at) |
Name Check After Ingest
The name field is parsed from SKILL.md frontmatter and may be generic (e.g., tools, gas). Always check the ingest log output. Fix ambiguous names before approving — use the DB update snippet in references/commands.md.
Good naming: gas → Ethereum Gas Tracker, tools → Ethereum Developer Tools, opensea → OpenSea NFT API
Primary Categories
Stocks, Macro, Crypto, Developer, Social
Use category only for the single top-level browse bucket.
Use labels for overlapping metadata such as:
analytics, signals, screening, portfolio, research, execution, mcp, options, defi, ethereum, news, twitter
Do not duplicate built-in capability fields with labels. These are already first-class DB columns:
requires_secrets, requires_private_keys, requires_exchange_api_keys, can_sign_transactions, uses_leverage, accesses_user_portfolio
Risk Tiers
low (read-only/analysis), medium (writes, no keys), high (keys, signing, leverage)
Common Quick Commands
# List skills
uv run python -m mesh.skill_marketplace.scripts.list_skills
uv run python -m mesh.skill_marketplace.scripts.list_skills --status draft
uv run python -m mesh.skill_marketplace.scripts.list_skills --status verified
# Update category + labels
curl -X PATCH https://mesh.heurist.xyz/admin/skills/SKILL_ID/taxonomy \
-H "X-API-Key: $INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"category": "Crypto", "labels": ["defi", "analytics"]}'
# Approve
uv run python -m mesh.skill_marketplace.scripts.approve_skill --slug my-skill
# Check upstream changes
uv run python -m mesh.skill_marketplace.scripts.check_upstream
Update Skill Content (Preferred)
Use --update to update an existing skill in place — no need to delete first. Preserves id, download_count, star_count, and created_at. Resets status to draft so you must re-approve.
# 1. Update from source
uv run python -m mesh.skill_marketplace.scripts.ingest_skill \
--url https://raw.githubusercontent.com/OWNER/REPO/main/SKILL.md \
--slug my-skill \
--category Crypto \
--label defi \
--source-url https://github.com/OWNER/REPO \
--update
# 2. Re-approve
uv run python -m mesh.skill_marketplace.scripts.approve_skill --slug my-skill
Other Operations
For reject, remove, update metrics, update external API dependencies, update reference URLs, local file/dir ingest, and Admin HTTP API calls — see references/commands.md.