Templates

A Template is a reusable starting point for an Agent. It combines profile metadata, standing instructions, Skills, and a live file tree that Skopik copies into each Agent created from it.

Templates are starting points, not inheritance. Existing Agents do not change automatically when their source Template changes.

Create a Template

name is an immutable lowercase kebab-case identifier. Use files to seed AGENTS.md and supporting content.

const template = await skopik.templates.create({
	name: 'research-analyst',
	displayName: 'Research Analyst',
	description: 'A source-first analyst for concise decision briefs.',
	instructions: 'Separate evidence, inference, and recommendation.',
	tags: ['research', 'analysis'],
	files: [
		{
			path: 'AGENTS.md',
			content: '# Research analyst\n\nUse primary sources and include direct URLs.\n',
			contentType: 'text/markdown',
		},
		{
			path: 'references/brief-format.md',
			content: '# Brief format\n\n1. Executive summary\n2. Evidence\n3. Recommendation\n',
			contentType: 'text/markdown',
		},
	],
})

curl "https://api.skopik.com/api/v1/templates" \
  -H "Authorization: Bearer $SKOPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-analyst",
    "display_name": "Research Analyst",
    "description": "A source-first analyst for concise decision briefs.",
    "instructions": "Separate evidence, inference, and recommendation.",
    "tags": ["research", "analysis"],
    "files": [{
      "path": "AGENTS.md",
      "content": "# Research analyst\n\nUse primary sources and include direct URLs.\n",
      "content_type": "text/markdown"
    }]
  }'

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

Add Skills

skills contains Skill ids that should be copied into every Agent created from the Template:

const sourceReview = await skopik.skills.upsert({
	name: 'source-review',
	displayName: 'Source Review',
	description: 'Checks whether important claims have credible primary sources.',
	files: [{
		path: 'SKILL.md',
		content: '# Source review\n\nVerify every material claim against a primary source.\n',
	}],
})

const template = await skopik.templates.upsert({
	name: 'research-analyst',
	displayName: 'Research Analyst',
	description: 'A source-first analyst for concise decision briefs.',
	instructions: 'Separate evidence, inference, and recommendation.',
	tags: ['research', 'analysis'],
	skills: [sourceReview.skillId],
})

When Skopik creates an Agent, each Skill tree is copied under the Agent's skills/ directory. See Skills for authoring details.

Create an Agent from a Template

Use a Template directly while opening a Session:

const session = await skopik.sessions.open({
	template: template.templateId,
	prompt: 'Research the current market and write a decision brief.',
	permission: 'ask',
})

console.log(session.agentId)

This creates an active Agent and starts its opening Session in one request. You can add Skills for just this new Agent:

await skopik.sessions.open({
	template: template.templateId,
	skills: [additionalSkillId],
	prompt: 'Research the current market and write a decision brief.',
})

To create the Agent without opening a Session:

const { agent, operation } = await skopik.templates.use(template.templateId, {
	name: 'market-researcher',
	displayName: 'Market Researcher',
	status: 'active',
})

templates.use() defaults the new Agent to draft; pass status: 'active' when it should be ready to open Sessions immediately.

List and get Templates

const { data: templates } = await skopik.templates.list({
	tags: ['research'],
})

const template = await skopik.templates.get(templates[0].templateId)

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

Update or upsert

const updated = await skopik.templates.update(template.templateId, {
	displayName: 'Senior Research Analyst',
	instructions: 'Prefer primary sources and state confidence explicitly.',
	tags: ['research', 'analysis', 'senior'],
})

Use upsert() for repeatable configuration keyed by immutable name:

const template = await skopik.templates.upsert({
	name: 'research-analyst',
	displayName: 'Research Analyst',
	description: 'A source-first analyst for concise decision briefs.',
	instructions: 'Prefer primary sources and state confidence explicitly.',
	files: [{
		path: 'AGENTS.md',
		content: '# Research analyst\n\nUse primary sources and include direct URLs.\n',
	}],
})

For Templates you own, files on update or upsert replaces the named seed paths in the live tree.

Manage Template files

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

const target = template.templateId

await skopik.files.writeText(
	{ target, path: 'references/source-policy.md' },
	{
		content: 'Use the primary source behind every material claim.\n',
		contentType: 'text/markdown',
	},
)

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

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

Use file ETags and ifMatch for safe concurrent updates.

Archive a Template

await skopik.templates.archive(template.templateId)

Archiving prevents new Agents from using the Template. Agents already created from it keep their copied profile and brain.

API reference