> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/stackai-tools/skill-management/update-skill.md).

# Update Skill

Publish a new version of an existing skill when its instructions, actions, or supporting files need to change.

## Before you start

You need permission to update the selected skill.

## Publish a skill update

1. Use [Get Skill](https://docs.stackai.com/stackai-tools/skill-management/get-skill.md) to review the current content, then select its **Skill ID** for the update.
2. Supply the fields you want to change. Choose **Existing Files** carefully: keep previous files and add the supplied files, or replace the file set with exactly what you provide.
3. Validate the proposed content, then run **Update Skill**.
4. Check the new **Version**, stored **Instructions**, **Actions**, and **Files** before using the update.

**Result:** The action publishes a new latest version of the selected skill.

## Behavior and troubleshooting

Built-in skills are read-only. Replacing existing files can remove supporting files omitted from the update. Keep the returned version number so you can compare it with history or restore an earlier version.

## Inputs

| Field               | Parameter        | Description                                                                                                                                        |
| ------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Skill ID (required) | `skill_id`       | The ID of the skill to publish a new version of.                                                                                                   |
| Name                | `name`           | The skill's name. Changing it renames the skill.                                                                                                   |
| Description         | `description`    | What the skill does and when to use it.                                                                                                            |
| Instructions        | `instructions`   | The skill's instructions, in markdown.                                                                                                             |
| Actions             | `actions`        | Action refs the new version may use.                                                                                                               |
| File Source         | `file_source`    | Choose how all optional new supporting files are provided.                                                                                         |
| Supporting Files    | `text_files`     | Optional text files, each with a bundle name and inline content.                                                                                   |
| Supporting Files    | `url_files`      | Optional files fetched from URLs, each with its bundle name.                                                                                       |
| Existing Files      | `existing_files` | What to do with the previous version's supporting files. Keep them and add anything supplied above, or replace them with exactly what is supplied. |

## Outputs

| Field         | Parameter       | Description                                             |
| ------------- | --------------- | ------------------------------------------------------- |
| Summary       | `summary`       | One-line summary of what was published.                 |
| Skill ID      | `skill_id`      | The skill that was updated.                             |
| Name          | `name`          | The published skill name.                               |
| Version       | `version`       | The new latest version number.                          |
| Description   | `description`   | The published description.                              |
| Actions       | `actions`       | Action refs stored with the new version.                |
| Instructions  | `instructions`  | The stored SKILL.md body.                               |
| Frontmatter   | `frontmatter`   | The stored SKILL.md frontmatter.                        |
| Files         | `files`         | The new version's file manifest (metadata only).        |
| Normalization | `normalization` | What the import process changed; only set in file mode. |

## Related guidance

[Skill Instructions, Files, and Action References](https://docs.stackai.com/technical-reference/models-agents-and-skills/skill-instructions-files-and-action-references.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/stackai-tools/skill-management/update-skill.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
