> This page is for API Reference & Tools. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.moveworks.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server. # Assistant skills (Configuration API) > Register and replace Skill bundles for Productivity Assistants through the Moveworks Configuration API: upload flow, bundle limits and update rules. `assistant.skills` The assistant skills entity registers [Skills](/harness/agentic-orchestrator/skills) from uploaded bundles, so that [productivity assistants](/api-reference/configuration-api/productivity-assistants/overview) can use them. A Skill's `name`, `description` and `surfaces` always come from the `SKILL.md` file in its bundle. The only thing you send is the `file_id` of a bundle uploaded through the Files API. Deleting a Skill isn't available through the API. > **Controlled Availability** > > Productivity Assistants are in Controlled Availability. Capabilities, limits, and interface labels described here may change before general availability. To request access, contact your Moveworks account team. * **Endpoint:** `/assistant/skills` | **Methods:** GET, PATCH, POST * **Request shape:** fields go at the top level of the JSON body. These endpoints take no `resource` wrapper, and the Skill's `id` goes in the URL, not the body. * **Schemas, examples and errors:** each endpoint page below lists every field, example requests and responses, and the errors it can return. ## Configuration API request basics | Setting | Value | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Base URL | `https://api.moveworks.ai/configurations/v1alpha1` | | Authentication | `Authorization: Bearer ` on every request. Moveworks issues Configuration API keys. The key identifies your organization, so no organization name goes in the URL. | | Content type | `application/json` | | Rate limit | 120 requests per minute for each organization. Above that, the API returns `429`; wait and retry. | | Versioning | Every create and update needs `version.change_description`. Every update also needs the `version.num` from your last read; if the document changed since then, the update returns `409`. | | Delete | Not available in `v1alpha1`. | ## Assistant skill endpoints Configuration API paths are relative to the base URL above. The upload is a Files API call with its own base URL. | Method | Path | Endpoint reference | | ------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | `POST` | `https://api.moveworks.ai/rest/v1alpha1/files` | [Upload file](/api-reference/alpha-files-api/files/upload-file), with purpose `CONFIGURATIONS_ASSISTANT_SKILL` | | `POST` | `/assistant/skills` | [Register skill](/api-reference/configuration-api/assistant-skills/register-skill) | | `GET` | `/assistant/skills` | [List skills](/api-reference/configuration-api/assistant-skills/list-skills) | | `GET` | `/assistant/skills/{id}` | [Get skill](/api-reference/configuration-api/assistant-skills/get-skill) | | `PATCH` | `/assistant/skills/{id}` | [Replace skill bundle](/api-reference/configuration-api/assistant-skills/replace-skill-bundle) | ## Calls that register a Skill Registering a Skill takes two calls, and a third to give it to an assistant. | Order | Call | Result | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | 1 | [Upload file](/api-reference/alpha-files-api/files/upload-file): send the `.zip` or `.skill` bundle with purpose `CONFIGURATIONS_ASSISTANT_SKILL`. The `purpose` part must come before the `file` part. | A file `id`, valid for 24 hours. | | 2 | [Register skill](/api-reference/configuration-api/assistant-skills/register-skill): send that `id` as `file_id`. | The registered Skill, with its own `id`. | | 3 | [Update productivity assistant](/api-reference/configuration-api/productivity-assistants/update-productivity-assistant): add the Skill's `id` to `skill_ids`. | The assistant can use the Skill. | The uploaded file is only a staging copy. Registering the Skill copies the bundle into permanent storage, so the Skill keeps working after the upload expires. ## Skill bundle requirements What goes inside a bundle, including the `SKILL.md` format, is described in [Bundle format](/harness/agentic-orchestrator/skills#bundle-format). These limits apply to a bundle sent through the API: | Item | Rule | | ------------------- | ------------------------------------------------------------------------------------ | | File type | `.zip` or `.skill`, one Skill per file | | Upload size | Up to 100 MB | | Unpacked size | Up to 100 MiB, in up to 1,000 files | | `SKILL.md` location | At the root of the archive, or inside one folder named exactly as the Skill's `name` | | `name` | 1 to 64 characters: lowercase letters, digits and single hyphens | | `description` | Up to 1,024 characters | | Upload purpose | `CONFIGURATIONS_ASSISTANT_SKILL` | | Time to register | Within 24 hours of the upload, before the file expires | ## How assistant skill updates behave * **`file_id` is the only field you can change.** A `PATCH` that sends `name`, `description` or `surfaces` is rejected. To change them, edit `SKILL.md` and upload a new bundle. * **The Skill keeps its `name`.** A replacement bundle whose `SKILL.md` names a different Skill is rejected. Register it as a new Skill instead. * **Replacing a bundle with identical contents changes nothing.** The request succeeds and returns the current Skill, so a retry is safe. * **The last replacement wins.** `version.num` is checked against the stored Skill before the bundle is replaced. Two replacements sent at the same moment with the same `num` can both succeed, and the later one is stored. * **A rejected bundle doesn't change the Skill.** The bundle is checked before the Skill is created or replaced. * **A bundle that is still being scanned returns `409`.** The message asks you to retry in a few seconds, and the same request succeeds once the scan finishes. ## Related pages * [Productivity assistants (Configuration API)](/api-reference/configuration-api/productivity-assistants/overview): reference a Skill's `id` in `skill_ids` * [Skills](/harness/agentic-orchestrator/skills): what a Skill is and how to write `SKILL.md` * [Upload file](/api-reference/alpha-files-api/files/upload-file): the Files API call that uploads the bundle