Publish an organization skill
publish_skillPublish the next version of an organization skill that exists. To share a skill with the team, such as one the user keeps locally, call create_service with kind skill and then this; every member's agent can then read it. Pass exactly one of edits, files, or push. Prefer edits to change some files of a skill: each replaces or adds one file and keeps every other file, binary files included. files replaces the whole skill with a SKILL.md and any supporting text files, and drops every file it leaves out, binary files included. push is the id create_push returned and the commit you pushed, which carries any file. skill is required with edits and push; with files it defaults to the SKILL.md frontmatter name. The SKILL.md frontmatter must name the skill.
Pass base_version, the version get_skill reported, so a teammate's publish in between is not overwritten. It is required with edits. When the skill has moved past it, nothing is published: read the skill again and redo the change. A new skill starts with create_service with kind skill; a name that holds no skill is refused.
Publishing under a well-known name, such as governance, security, or design-system, replaces what Valet would otherwise supply for every agent in the organization from the next read on, so do it when the user has asked to change how the organization works, and show them the content first; its first publish works without create_service. A skill under a new name is one the default governance process finds through list_skills when its description applies.
Destructive because it replaces the previous version's content for every reader. Repeating a call with identical content mints no new version and reports deduped. Pass an idempotency_key so a retry after a lost answer returns the first call's result instead of publishing again. Requires connecting a Valet account.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| push | No | Publish a Git push instead of files: the id create_push returned and the commit you pushed to its branch. Use it when you can run git with network access, because it sends only what changed. Pass files or push, not both; every other argument keeps its meaning. | |
| edits | No | Files to change as [{path, content}], text only, paths relative to the skill root. Each replaces or adds that file; every other file is kept, binary files included, and all of them land in one new version. Requires skill and base_version. Pass one of edits, files, or push. | |
| files | No | The skill's whole tree as [{path, content}], text only, paths relative to the skill root. Must include SKILL.md, the complete definition with name and description frontmatter. Replaces the whole skill: a file it leaves out is removed, binary files included. Pass one of edits, files, or push. | |
| skill | No | The skill's name. Required with edits and push; with files, omit it to use the SKILL.md frontmatter name. | |
| org_name | No | The Valet organization to publish into. Omit to use the organization the account joined first. | |
| base_version | No | The version get_skill reported, 0 for Valet's default. The publish is refused, and nothing is published, when the skill's latest version is not this one. Required with edits; optional with files and push. | |
| idempotency_key | No | An opaque key of your choosing. Repeating a call with the same key returns the first call's result instead of publishing again, which makes a retry safe. |