@kody/skills

@kody/skills — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, bulk git lane, and edge cases. Do not disable live webhooks or jobs (including the repo.pushed subscription that resyncs skills_index).

Auth

Zero-auth. No OAuth, secrets, or required hosts.

Prefer static imports of your fork (kody:@you/skills/...). The live @kody/skills package bucket is shared platform storage.

Import paths

Prefer static kody:@kody/skills/... (or your fork) imports from execute. Do not lead with packages.invoke. Do not guess skill ids — list first.

Smoke / quickstart

import skillList from 'kody:@kody/skills/skill-list'
import skillGet from 'kody:@kody/skills/skill-get'
import skillSave from 'kody:@kody/skills/skill-save'

export default async function main() {
	const preview = await skillSave({
		id: 'my-skill',
		path: 'SKILL.md',
		content: '# My skill\n\nInstructions here…',
		name: 'my-skill',
		description: 'What this skill is for and when an agent should load it.',
		dryRun: true,
	})
	const index = await skillList()
	return { preview, index }
}

After a confirmed live save:

import skillGet from 'kody:@kody/skills/skill-get'

export default async function main() {
	return await skillGet({ id: 'my-skill' })
}

Version recovery:

import skillHistory from 'kody:@kody/skills/skill-history'
import skillRevert from 'kody:@kody/skills/skill-revert'

export default async function main() {
	const history = await skillHistory({
		id: 'my-skill',
		path: 'SKILL.md',
		limit: 10,
	})
	return await skillRevert({ version_id: history[0].version_id, dryRun: true })
}

dryRun (mutations)

skill_save, skill_delete, skill_revert, and migrate-to-repo accept dryRun: true. Preview that way before a live write.

Bulk edits (git lane)

For multi-file refactors, skip per-file skill_save and edit the account's own plain repo:

1. repo_get_git_remote({ name: "skills", scope: "write" })
2. Clone locally, edit skill directories ({id}/SKILL.md, {id}/skill.json, …)
3. Commit and push — plain repos are live-at-HEAD (no package publish step)

Kody enforces a 10 MiB per-file gate on session/file writes; the direct git lane is bounded only by Artifacts (~32 MiB per push pack).

Keeping list/search current

• skill_get always reads the live repo HEAD when the backend is repo.
• skill_list / skill-search use a fast skills_index projection in package storage.
• skill_save / skill_delete update that index in the same call.
• Git-lane pushes to the plain skills repo fire repo.pushed; this package resyncs skills_index. Leave that subscription enabled.
• Manual fallback: import migrateToRepo from 'kody:@kody/skills/migrate-to-repo' then migrateToRepo({ dryRun: true }).

Export shapes

Retriever / durable layout

Retriever: package.json#kody.retrievers scopes ["search", "context"]. Matching is case-insensitive over skill name + description. Soft-fails empty if storage is slow (~250ms budget).

Optional plain repo name: skills (per account — repo_create, never copy another user's remote):

README.md
{skill-id}/
  skill.json
  SKILL.md
  ...optional reference files

Fresh forks start on legacy packageStorage() tables. After you populate a skills repo, migrate-to-repo({ switch_reads: true }) points reads at the repo. Legacy tables stay intact.

Conventions / edge cases

• Skill ids are lower-kebab-case (for example writing-style).
• Give each skill a SKILL.md entry file; add reference files alongside.
• Make description complete enough that an agent can decide from skill_list alone whether to load the skill.
• Do not bake personal skill documents, personal git remotes, or another account's registry into this package.