[ INTEGRATION ]
Skills
Skills are folders an agent can discover, fetch, and run. A skill is just a directory containing a SKILL.md (with YAML frontmatter for name + description) and any helper files the author shipped: scripts, configs, prompts, examples. The agent fetches the whole folder and decides what to do with it.
⚠Private beta — provisioning required
Skills must be enabled on your platform by an Assistiv admin. The MCP tools (find_skill, fetch_skill, create_skill, submit_skill_review) only register when platform.skills_enabled = true. Email founders@assistiv.ai to provision.
ℹFree tier
First 5,000 skill calls per platform per calendar month are free (combined across all four MCP tools). After 5k, $0.0004 per call ($0.40 per 1k) — flat regardless of skill folder size, since size is set by the source repo, not by you. Counter resets on the 1st of each month. See pricing for the full tier table.
What's in a skill
A skill is a directory. The only required file is SKILL.md with frontmatter for the searchable name and description. Everything else in the folder is fair game: Python, shell scripts, TypeScript, configs, README, examples.
my-skill/
├── SKILL.md ← required, with YAML frontmatter
├── run.py ← optional helper
├── prompts/
│ └── system.md
└── README.md
# SKILL.md
---
name: my-skill
description: One-line summary used by find_skill ranking.
---
# Body
Whatever the agent should read after fetching.Public vs. private skills
Public
Synced from admin-vetted GitHub repos. Anyone on any platform with skills enabled can find and fetch them. Updates land within ~30 seconds of a commit. You don't upload these — Assistiv admins register the source repos.
Private
Uploaded by your platform via create_skill. Encrypted at rest in GCS. Visible only to the owner — either the platform (sk-plat_) or the end-user (sk-eu_). End-user-owned skills survive API key rotation.
Lifecycle
From the agent's perspective: search, fetch, run, review.
Admin Sweeper Agent find_skill fetch_skill
───── ─────── ───── ────────── ───────────
Adds GitHub → Clones, walks → (later, on need) Hybrid retrieval Returns full
repo to → every SKILL.md → calls find_skill → BM25 + pgvector → folder bytes
admin UI Hashes folder with a query + review boost + target_path
Indexes instruction
↓ ↓
Top-K matches Agent's runtime
with summaries writes files,
runs the skill
↓
submit_skill_review
accuracy / value /
efficiency / clarity
1-5 each, drives
ranking next timeOwnership model
| Who creates | Visibility | Owner field set | Survives key rotation? |
|---|---|---|---|
| Platform key (sk-plat_) | private | owner_platform_id | N/A — platform keys don't rotate per-user |
| End-user key (sk-eu_) | private | owner_end_user_id | Yes — owned by the end-user, not the key |
| Assistiv admin | public | neither (synced from a registered repo) | N/A |
Quality model — agent reviews drive ranking
There's no LLM judge. Quality comes from real usage signal. After fetching and running a skill, the agent submits a four-dimension review (1-5 each):
Accuracy
Did the skill do what its description said?
Value
Was the result useful for the task?
Efficiency
Tokens, time, side effects within reason?
Clarity
Was SKILL.md clear enough first try?
One review per (skill, end-user). Resubmits overwrite. The composite score boosts well-reviewed skills on the next find_skill call — it never punishes new ones, so a brand-new skill gets a fair shot.
Using skills from an agent (MCP)
When skills are enabled on your platform, the following 5 MCP tools auto-register on every per-user MCP URL. Full tool reference and a three-call curl quickstart live on the Skills MCP page. REST endpoints are documented in the Skills API reference.
Dedupe by content
Plugin-bundle repos often ship the same skill at multiple paths (e.g., plugins/agent-A/skills/foo and plugins/agent-B/skills/foo). The sync sweeper hashes the full folder and collapses identical content to one row. Agents see one match per unique skill, not seven copies of the same thing.