Skills

A Skill is a reusable capability bundle. Its SKILL.md tells an Agent when and how to apply the capability; optional references, scripts, examples, and assets live beside it.

Skills compose behavior without cloning an Agent or duplicating a complete Template.

Author SKILL.md

Every Skill starts with SKILL.md at its root. Keep the description specific enough that an Agent can decide when the Skill applies.

---
name: source-review
description: Verify material claims against credible primary sources.
---

# Source review

1. Identify every material factual claim.
2. Prefer the original paper, filing, standard, or vendor documentation.
3. Mark unsupported claims and distinguish inference from evidence.
4. Return the source URL beside each finding.

A typical tree is:

SKILL.md
references/
  source-quality.md
scripts/
  check-links.ts
examples/
  review.md

Create a Skill

name is an immutable lowercase kebab-case identifier. displayName, description, tags, icon, and files can change later.

const skill = await skopik.skills.create({
	name: 'source-review',
	displayName: 'Source Review',
	description: 'Verifies material claims against credible primary sources.',
	tags: ['research', 'quality'],
	files: [
		{
			path: 'SKILL.md',
			content: `---
name: source-review
description: Verify material claims against credible primary sources.
---

# Source review

Check every material claim and return its primary source URL.
`,
			contentType: 'text/markdown',
		},
		{
			path: 'references/source-quality.md',
			content: '# Source quality\n\nPrefer original publications and official records.\n',
			contentType: 'text/markdown',
		},
	],
})

curl "https://api.skopik.com/api/v1/skills" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "source-review",
    "display_name": "Source Review",
    "description": "Verifies material claims against credible primary sources.",
    "tags": ["research", "quality"],
    "files": [{
      "path": "SKILL.md",
      "content": "# Source review\n\nCheck every material claim and return its primary source URL.\n",
      "content_type": "text/markdown"
    }]
  }'

The SDK returns the Skill directly. Metadata routes accept either its skillId or immutable slug; file operations use skillId as the target.

Use a Skill

Add Skill ids to a Template when every Agent created from that Template should receive them:

await skopik.templates.update(templateId, {
	skills: [skill.skillId],
})

Add Skills while opening a Session from a Template when only that newly created Agent needs them:

const session = await skopik.sessions.open({
	template: templateId,
	skills: [skill.skillId],
	prompt: 'Review this market brief and flag weakly sourced claims.',
})

When Skopik creates the Agent, it copies each Skill's current live tree under skills/{skillName}/ in the Agent brain. The Agent then owns that copy; later Skill edits do not silently change existing Agent behavior.

List and get Skills

const { data: skills } = await skopik.skills.list({
	tag: 'research',
})

const skill = await skopik.skills.get(skills[0].skillId)

curl "https://api.skopik.com/api/v1/skills?tag=research" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Update or upsert

const updated = await skopik.skills.update(skill.skillId, {
	displayName: 'Primary Source Review',
	description: 'Verifies material claims against original publications and official records.',
	tags: ['research', 'quality', 'citations'],
})

Use upsert() for rerunnable Skill setup keyed by immutable name:

const skill = await skopik.skills.upsert({
	name: 'source-review',
	displayName: 'Primary Source Review',
	description: 'Verifies material claims against original publications and official records.',
	files: [{
		path: 'SKILL.md',
		content: '# Source review\n\nVerify every material claim against an original source.\n',
	}],
})

Manage Skill files

Skill files are live and versionless. Use the file client with the Skill id as target:

const target = skill.skillId

await skopik.files.writeText(
	{ target, path: 'references/source-quality.md' },
	{
		content: '# Source quality\n\nPrefer original publications and official records.\n',
		contentType: 'text/markdown',
	},
)

const instructions = await skopik.files.readText({
	target,
	path: 'SKILL.md',
})

const { data: files } = await skopik.files.list({ target })

Use file ETags and ifMatch for safe concurrent updates. The same client can move, remove, upload, and download files.

Archive a Skill

await skopik.skills.archive(skill.skillId)

Archiving prevents new installations. Existing Agents retain the copies already present in their brains.

API reference