---
title: "Rename a skill file"
method: POST
path: "/v2/skills/{skill_id}/files/rename"
tags: ["Skills"]
---

# Rename a skill file

`POST /v2/skills/{skill_id}/files/rename`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v2/skills/{skill_id}/files/rename`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/orq-ai/apis/orq-ai-api/docs/v2/skills/:skill_id/files/rename/post.ts> (a function with typed inputs; its response is checked against the schema)

Changes a file's path within a skill's bundle. The file content is unchanged. SKILL.md cannot be renamed.

## Path parameters

- `skill_id` string, required

## Request body

- RenameSkillFileRequest
  - `old_path` string, required: Current relative path of the file within the skill bundle.
  - `new_path` string, required: New relative path for the file within the skill bundle, including any subdirectory components (e.g. "scripts/extract.py").

## Response `200`

OK

- RenameSkillFileResponse
  - `skill` Skill, required
    - `skill_id` string, required: Unique skill identifier assigned by ORQ, for example `skill_01H...`. Use this value in retrieve, update, and delete requests.
    - `display_name` string, required: Workspace-unique display name. Must start with a letter and may contain letters, numbers, dashes, and underscores. Dots are not allowed.
    - `description` string, required: Short human-readable summary of what the skill is for.
    - `tags` string[], required: Free-form labels used for organization and filtering in clients.
    - `project_id` string, required: Project that owns or contains the skill.
    - `path` string, required: Project path where the skill is stored in the workspace.
    - `created_at` string, date-time, required: Time when the skill was created.
    - `updated_at` string, date-time, required: Time when the skill was last updated.
    - `created_by_id` string, required: User ID that created the skill.
    - `updated_by_id` string, required: User ID that last updated the skill.
    - `instructions` string, required: Instruction body executed or reused by clients that load this skill.
    - `version` string, required: Latest semver for the skill. It advances when the skill's definition changes and is returned on every read.
    - `files` SkillFile[]
      - `path` string, required: Relative path within the skill bundle, including any subdirectory components (e.g. "scripts/extract.py").
      - `size_bytes` string, required: Size of the file in bytes.
      - `sha256` string, required: SHA-256 hex digest of the file content; used as the content-addressed storage key.
      - `content_type` string, required: MIME type of the file content.
    - `has_files` boolean
    - `repository_source` SkillRepositorySource
      - `connection_id` string
      - `repository_url` string
      - `ref` string
      - `subdirectory` string
      - `commit_sha` string

## Other responses

- `401`: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.

## Changes

> 1181 revisions in range; 72 not diffed.

- **2026-11-10** `764b5375e61f`: 1 info
  - endpoint added
- **2026-11-10** `b01d20a20f31`: 1 breaking
  - api path removed without deprecation
- **2026-11-10** `47458d9f193c`: 1 info
  - endpoint added
- **2026-11-09** `590c68626991`: 1 breaking
  - api path removed without deprecation
- **2026-11-09** `259a2ea1deec`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/skills/:skill_id/files/rename/post.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/c3f024f8fcb0?raw)