Skills and Imports

A skill is reusable Markdown/text knowledge or procedure an agent loads when relevant. Skills are not connections, MCP servers, or tools. Alpha imports normalize to Markdown/text only — archives containing scripts, binaries, or hooks are rejected at scan time with actionable findings.

author/paste → draft version → validate → staged import → review → publish (immutable)

• POST /v1/skills creates the stable identity (name, slug, visibility).
• POST /v1/skills/:id/versions drafts content; every draft carries scan findings and a blocked flag.
• POST .../publish requires zero blocking findings. Published versions are immutable; tenants keep working when you deprecate and replace.
• Agent versions pin skill versions in their manifest (skills: [{ skill_version_id }]). Publishing an agent validates that each referenced skill version is published.

POST /v1/skill-imports accepts exactly one source — repository (public GitHub, fetched as an archive), url (raw file or zip), text/files (paste), or multipart file (zip/md/txt). The import is normalized (Markdown/text kept, traversal and executables rejected), scanned, and staged as ready_for_review. Nothing becomes a production capability automatically.

Repository imports accept ref (branch/tag/SHA, default HEAD) and subdir to scope large repos — /tree/<ref>/<subdir> deep links are parsed too. Archives are pre-filtered to Markdown/text (.md/.markdown/.mdx/.txt) with node_modules, .git, and other vendor clutter skipped and reported as a repo_filtered warning instead of failing the import.

Plain web pages passed as url have readable text extracted (reported as an html_extracted warning); binary content-types are rejected with 415. Alpha caps stay at 50 files, 200 KB per file, 2 MB total — oversize failures now return 413 with actual-vs-limit numbers, the offending path, and request_id under error.details (the code stays invalid_request_error).

The scanner flags secrets (AWS keys, private keys, tokens), prompt-injection patterns, binaries, archive bombs, and oversized packages as blockers; external links are warnings. POST .../publish with name creates the skill and emits an immutable published version pinned to the scanned checksum.

Sessions installed from a version with skill pins load published skill contents into context (capped, tenant-private skills only for their tenant). Skills never carry credentials.

const skill = await cencori.skills.create({ name: 'Refund policy' });
await cencori.skills.createVersion(skill.id, { version: '1.0.0', content: '# Refunds\n\n30 days.' });
await cencori.skills.publishVersion(skill.id, '1.0.0', { reviewed_by: 'bola' });