SDK reference · Resources
client.skills
client.skills.{ list, get, create, update, approve, reject, archive, packs, installPack }A skill is a reusable procedure in the Agent Skills format: a kebab-case name, a description saying what it does and when to use it, and a markdown body. Jobs carry the approved skills from when they were created, see each one's name and description, and load a procedure when it fits the task.
Skills are never edited in place: editing an approved skill saves a new revision and archives the old one, which approve restores.
list
list(options?: { status?: "approved" | "proposed" | "rejected" | "archived" | "all"; name?: string }): Promise<Page>Skills without their bodies, newest first.
Parameters
options.statusstringoptional- Which skills; approved by default.
options.namestringoptional- Every revision of one skill, with status all.
Returns Promise<Page>
get
get(id: string): Promise<Resource>A skill with its body.
Parameters
idstring- The skill's ID.
Returns Promise<Resource>
create
create(input: SkillInput): Promise<Resource>Adds an approved skill. Fails with skill_exists when an approved skill has the name.
Parameters
input.namestring- Lowercase letters, digits and hyphens.
input.descriptionstring- What it does and when to use it.
input.bodystring- The procedure, in markdown.
input.settingsSkillSettingsoptional- Connectors it needs or can use, and actions it always asks before.
Returns Promise<Resource>
await client.skills.create({
name: "weekly-invoice-summary",
description: "Summarises this week's invoices. Use when asked about bills.",
body: "## Procedure\n\n1. Search email for invoices from the last 7 days.",
settings: { connectors: { required: ["gmail"] } },
});update
update(id: string, input: SkillInput & { version: number }): Promise<Resource>Edits a skill. An approved skill gets a new revision; version must be the one you last read, or the call fails with skill_changed.
Parameters
idstring- The skill's ID.
input.versionnumber- The version you edited.
Returns Promise<Resource>
approve
approve(id: string): Promise<Resource>Approves a proposed skill or restores an archived one, archiving the approved skill of the same name.
Parameters
idstring- The skill's ID.
Returns Promise<Resource>
reject
reject(id: string, reason?: string): Promise<Resource>Rejects a proposed skill.
Parameters
idstring- The skill's ID.
reasonstringoptional- Kept with the skill.
Returns Promise<Resource>
archive
archive(id: string): Promise<Resource>Archives an approved skill; new jobs stop carrying it.
Parameters
idstring- The skill's ID.
Returns Promise<Resource>
packs
packs(): Promise<Page>The starter packs, with each skill's connectors and whether the application has it.
Returns Promise<Page>
installPack
installPack(id: string, skills?: string[]): Promise<{ installed: string[]; skipped: string[] }>Adds a pack's skills, or those named, as approved skills. Names the application already has are skipped.
Parameters
idstring- productivity, research, errands or work.
skillsstring[]optional- Only these skills from the pack.
Returns Promise<{ installed: string[]; skipped: string[] }>
await client.skills.installPack("errands", [
"product-search",
"book-restaurant-reservation",
]);