Skills

Skills are reusable capabilities that can be installed on agents. Use them when multiple agents should share the same tool behavior or workflow knowledge.

Every skill carries an editable draft file tree; publishing freezes the draft into a numbered version. Installing a skill pins a published version onto an agent, and agents.skills.sync() moves that install to a newer version later. Agents created from a template pull template updates separately with agents.syncFromTemplate().

Quick Links

Action	Description
`skills.list()`	List skills.
`skills.create()`	Create a skill with a draft file tree.
`skills.get()`	Fetch a single skill.
`skills.update()`	Update skill details.
`skills.archive()`	Archive a skill.
`skills.publish()`	Publish the draft as a new version.
`skills.duplicate()`	Copy a skill and its files.
`skills.listAgents()`	List agents with a skill installed.
`skills.files.list()`	List files in a skill tree.
`skills.files.read()`	Read a skill file.
`skills.files.write()`	Write a file in the draft tree.
`skills.files.delete()`	Delete a file from the draft tree.
`skills.files.move()`	Move or rename a draft file.
`agents.skills.install()`	Install a skill on an agent.
`agents.skills.sync()`	Update an installed skill to a newer version.
`agents.skills.remove()`	Uninstall a skill from an agent.

Example

Install the latest published version of a skill on an agent:

const { operation } = await client.agents.skills.install(agentId, { skillId })

operation = client.agents.skills.install(agent_id, skill_id=skill_id).operation

curl "$SKOPIK_API_BASE/agents/$AGENT_ID/skills" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"skill_id\": \"$SKILL_ID\" }"

Reference

`skills.list(params?)`

List reusable skills.

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

skills = client.skills.list(tag="research").data

curl "$SKOPIK_API_BASE/skills?tag=research" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Parameters

Field	Type	Required	Notes
`source`	string	No	Filter by `user` or `curated`.
`tag`	string	No	Filter by tag.

Returns ListResponse<Skill> = { data: Skill[], page? } — see Skill.

`skills.create(input)`

Create a skill. files seeds the draft tree, which you can keep editing with files.write() before publishing.

const { skill } = await client.skills.create({
	name: 'summarize-thread',
	description: 'Summarize a long conversation into decisions and open questions.',
	tags: ['research'],
	files: [
		{ path: 'SKILL.md', content: '# Summarize thread\nExtract decisions, owners, and open questions.' },
	],
})

skill = client.skills.create(
    name="summarize-thread",
    description="Summarize a long conversation into decisions and open questions.",
    tags=["research"],
    files=[{"path": "SKILL.md", "content": "# Summarize thread\nExtract decisions, owners, and open questions."}],
).skill

curl "$SKOPIK_API_BASE/skills" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarize-thread",
    "description": "Summarize a long conversation into decisions and open questions.",
    "tags": ["research"],
    "files": [{ "path": "SKILL.md", "content": "# Summarize thread\nExtract decisions, owners, and open questions." }]
  }'

Parameters

Field	Type	Required	Notes
`name`	string	Yes	Skill name.
`description`	string	No	Skill description.
`tags`	string[]	No	Tags.
`requiresConnection`	string	No	Connection provider the skill requires.
`metadata`	object	No	Customer metadata.
`files`	`{ path, content }[]`	No	Seeds the draft file tree.

Returns { skill: Skill } — see Skill.

`skills.get(skillId)`

Fetch a single skill.

const { skill } = await client.skills.get(skillId)

skill = client.skills.get(skill_id).skill

curl "$SKOPIK_API_BASE/skills/$SKILL_ID" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns { skill: Skill } — see Skill.

`skills.update(skillId, input)`

Update skill details. All fields are optional; only the fields you pass change.

const { skill } = await client.skills.update(skillId, {
	description: 'Summarize threads into decisions, owners, and open questions.',
})

skill = client.skills.update(
    skill_id,
    description="Summarize threads into decisions, owners, and open questions.",
).skill

curl "$SKOPIK_API_BASE/skills/$SKILL_ID" \
  -X PUT \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Summarize threads into decisions, owners, and open questions."
  }'

Parameters

Field	Type	Required	Notes
`name`	string	No	Skill name.
`description`	string	No	Skill description.
`tags`	string[]	No	Tags.
`requiresConnection`	string	No	Connection provider the skill requires.
`metadata`	object	No	Customer metadata.
`files`	`{ path, content }[]`	No	File entries written to the draft tree.

Returns { skill: Skill } — see Skill.

`skills.archive(skillId)`

Archive a skill.

await client.skills.archive(skillId)

client.skills.archive(skill_id)

curl "$SKOPIK_API_BASE/skills/$SKILL_ID" \
  -X DELETE \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns nothing — resolves when the API confirms the archive (HTTP 204).

`skills.publish(skillId)`

Publish the draft file tree as a new skill version. Publishing is asynchronous — the returned operation tracks it.

const { skill, operation } = await client.skills.publish(skillId)

skill = client.skills.publish(skill_id).skill

curl "$SKOPIK_API_BASE/skills/$SKILL_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns { skill: Skill, operation: Operation } — see Skill and Operation.

`skills.duplicate(skillId, input?)`

Copy a skill, including its files, into a new skill you own.

const { skill: copy, copiedFiles } = await client.skills.duplicate(skillId, {
	name: 'summarize-thread-v2',
})

copy = client.skills.duplicate(skill_id, name="summarize-thread-v2").skill

curl "$SKOPIK_API_BASE/skills/$SKILL_ID/duplicate" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "summarize-thread-v2" }'

Parameters

Field	Type	Required	Notes
`name`	string	No	Name for the copy.
`description`	string	No	Description for the copy.
`tags`	string[]	No	Tags for the copy.
`metadata`	object	No	Customer metadata.

Returns { skill: Skill, copiedFiles: number } — see Skill.

`skills.listAgents(skillId)`

List the agents that currently have the skill installed. This list is single-page.

const { data: agents } = await client.skills.listAgents(skillId)

agents = client.skills.list_agents(skill_id).data

curl "$SKOPIK_API_BASE/skills/$SKILL_ID/agents" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns ListResponse<SkillAgentRef> — one entry per agent with the skill installed.

`skills.files.list(skillId, params?)`

List files in a skill tree.

const { data: files } = await client.skills.files.list(skillId)

files = client.skills.files.list(skill_id).data

curl "$SKOPIK_API_BASE/skills/$SKILL_ID/files" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Parameters

Field	Type	Required	Notes
`version`	number	No	Published version to list. Omit for the draft tree.

Returns { version, data: CatalogFileEntry[] } — see CatalogFileEntry.

`skills.files.read(skillId, filePath, params?)`

Read a single skill file.

const { file } = await client.skills.files.read(skillId, 'SKILL.md')

file = client.skills.files.read(skill_id, "SKILL.md").file

curl "$SKOPIK_API_BASE/skills/$SKILL_ID/files/SKILL.md" \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Parameters

Field	Type	Required	Notes
`version`	number	No	Published version to read from. Omit for the draft tree.

Returns { file: CatalogFile } — see CatalogFile.

`skills.files.write(skillId, filePath, input)`

Write a file. Writes always target the draft tree — publish the skill to make them live.

const { file } = await client.skills.files.write(skillId, 'SKILL.md', {
	content: '# Summarize thread\nExtract decisions, owners, open questions, and deadlines.',
})

file = client.skills.files.write(
    skill_id,
    "SKILL.md",
    content="# Summarize thread\nExtract decisions, owners, open questions, and deadlines.",
).file

curl "$SKOPIK_API_BASE/skills/$SKILL_ID/files/SKILL.md" \
  -X PUT \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Summarize thread\nExtract decisions, owners, open questions, and deadlines."
  }'

Parameters

Field	Type	Required	Notes
`content`	string	Yes	File content.

Returns { file: CatalogFileEntry } — see CatalogFileEntry.

`skills.files.delete(skillId, filePath)`

Delete a file from the draft tree.

await client.skills.files.delete(skillId, 'notes.md')

client.skills.files.delete(skill_id, "notes.md")

curl "$SKOPIK_API_BASE/skills/$SKILL_ID/files/notes.md" \
  -X DELETE \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns nothing — resolves when the API confirms deletion (HTTP 204).

`skills.files.move(skillId, input)`

Move or rename a file in the draft tree.

const { data: files } = await client.skills.files.move(skillId, {
	from: 'notes.md',
	to: 'reference/notes.md',
})

files = client.skills.files.move(
    skill_id,
    from_="notes.md",
    to="reference/notes.md",
).data

curl "$SKOPIK_API_BASE/skills/$SKILL_ID/files/move" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "notes.md", "to": "reference/notes.md" }'

Parameters

Field	Type	Required	Notes
`from`	string	Yes	Current file path.
`to`	string	Yes	New file path.

Returns { data: CatalogFileEntry[] } — see CatalogFileEntry.

`agents.skills.install(agentId, input)`

Install a skill on an agent. Installation is asynchronous — the returned operation tracks it.

const { operation } = await client.agents.skills.install(agentId, {
	skillId,
	version: 3,
})

operation = client.agents.skills.install(agent_id, skill_id=skill_id, version=3).operation

curl "$SKOPIK_API_BASE/agents/$AGENT_ID/skills" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"skill_id\": \"$SKILL_ID\", \"version\": 3 }"

Parameters

Field	Type	Required	Notes
`skillId`	string	Yes	Skill id.
`version`	number	No	Published version to install. Defaults to latest.

Returns { operation: Operation } — see Operation.

`agents.skills.sync(agentId, skillId, input)`

Update a skill already installed on an agent to a newer published version. Syncing is asynchronous — the returned operation tracks it.

const { operation } = await client.agents.skills.sync(agentId, skillId, { toVersion: 4 })

operation = client.agents.skills.sync(agent_id, skill_id, to_version=4).operation

curl "$SKOPIK_API_BASE/agents/$AGENT_ID/skills/$SKILL_ID/sync" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_version": 4 }'

Parameters

Field	Type	Required	Notes
`toVersion`	number	No	Published version to sync to. Defaults to latest.

Returns { operation: Operation } — see Operation.

`agents.skills.remove(agentId, skillId)`

Uninstall a skill from an agent. Removal is asynchronous — the returned operation tracks it.

const { operation } = await client.agents.skills.remove(agentId, skillId)

operation = client.agents.skills.remove(agent_id, skill_id).operation

curl "$SKOPIK_API_BASE/agents/$AGENT_ID/skills/$SKILL_ID" \
  -X DELETE \
  -H "Authorization: Bearer $SKOPIK_API_KEY"

Returns { operation: Operation } — see Operation.

Types

`Skill`

Field	Type	Notes
`skillId`	string	Skill id.
`orgId`	string	Workspace id.
`name`	string	Skill name.
`description`	string	Skill description.
`tags`	string[]	Tags.
`currentVersion`	number	Latest published version.
`draftVersion`	number	Draft version.
`hasUnpublishedDraft`	boolean	Whether a draft differs from published.
`requiresConnection`	string \| null	Required connection provider.
`source`	string	`user` or curated source.
`metadata`	object	Customer metadata.
`createdAt`	string	ISO timestamp.
`updatedAt`	string	ISO timestamp.

`CatalogFile`

Field	Type	Notes
`path`	string	File path within the tree.
`content`	string	File content.

`CatalogFileEntry`

Field	Type	Notes
`path`	string	File path within the tree.
`dir`	boolean	Whether the entry is a directory.
`size`	number	File size in bytes.