> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a skill > Updates mutable skill fields. Omitted optional fields keep their current values. Repeated fields such as `tags` replace the existing collection when provided. ## OpenAPI ````yaml patch /v2/skills/{skill_id} openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - description: List models available through the AI Router. name: Models - name: Guardrail Rules - name: Policies - name: Routing Rules - name: API keys description: >- API keys authenticate programmatic access to the workspace. The unified key model exposes opaque tokens, per-domain access grants, and budget / rate-limit constraints (see ADR 0001 and ADR 0002). - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, api-key, provider, and model. A budget is hierarchical and defense-in-depth — every applicable budget is a hard gate, and the most restrictive one wins per dimension (see ADR 0007). - name: Documentation description: >- Search the orq.ai documentation. Proxies the workspace's query to the hosted docs search index. - name: Files description: File upload and retrieval operations. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Projects description: Projects organize resources within a workspace - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/skills/{skill_id}: patch: tags: - Skills summary: Update a skill description: >- Updates mutable skill fields. Omitted optional fields keep their current values. Repeated fields such as `tags` replace the existing collection when provided. operationId: SkillUpdate parameters: - name: skill_id in: path description: Skill ID to update. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateSkillRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UpdateSkillResponse' x-code-samples: - lang: curl label: Core - Update skill instructions source: | curl --request PATCH \ --url 'https://api.orq.ai/v2/skills/skill_01HZXW2K7Y8Q9M0N1P2R3S4T5V' \ --header 'Authorization: Bearer $ORQ_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "description": "Summarize support tickets for escalation handoff.", "tags": ["support", "handoff"], "instructions": "Return the issue summary, urgency, attempted fixes, and recommended owner." }' - lang: python label: Python - Update skill instructions source: | import os from orq_ai_sdk import Orq client = Orq(api_key=os.environ["ORQ_API_KEY"]) result = client.skills.update( skill_id="skill_01HZXW2K7Y8Q9M0N1P2R3S4T5V", description="Summarize support tickets for escalation handoff.", tags=["support", "handoff"], instructions=( "Return the issue summary, urgency, attempted fixes, " "and recommended owner." ), ) print(result.skill.version) - lang: typescript label: Node.js - Update skill instructions source: | import { Orq } from '@orq-ai/node'; const client = new Orq({ apiKey: process.env.ORQ_API_KEY, }); const result = await client.skills.update({ skillId: 'skill_01HZXW2K7Y8Q9M0N1P2R3S4T5V', description: 'Summarize support tickets for escalation handoff.', tags: ['support', 'handoff'], instructions: 'Return the issue summary, urgency, attempted fixes, and recommended owner.', }); console.log(result.skill.version); components: schemas: UpdateSkillRequest: required: [] type: object properties: display_name: type: string description: |- New workspace-unique display name. Omit to keep the current name. Must start with a letter and may contain letters, numbers, and underscores. Dashes and dots are not allowed because skill names are referenced as template variables. description: type: string description: New description. Omit to keep the current description. tags: type: array items: type: string description: Replacement tag list. Leave empty to clear tags. path: type: string description: New project path. Omit to keep the current path. instructions: type: string description: New instruction body. Omit to keep the current instructions. project_id: type: string description: New containing project. Omit to keep the current project. UpdateSkillResponse: required: - skill type: object properties: skill: allOf: - $ref: '#/components/schemas/Skill' description: Updated skill. Skill: required: - skill_id - display_name - description - tags - project_id - path - created_at - updated_at - created_by_id - updated_by_id - instructions - version type: object properties: skill_id: type: string description: |- Unique skill identifier assigned by ORQ, for example `skill_01H...`. Use this value in retrieve, update, and delete requests. display_name: type: string description: >- Workspace-unique display name. Must start with a letter and may contain letters, numbers, and underscores. Dashes and dots are not allowed. description: type: string description: Short human-readable summary of what the skill is for. tags: type: array items: type: string description: Free-form labels used for organization and filtering in clients. project_id: type: string description: Project that owns or contains the skill. path: type: string description: Project path where the skill is stored in the workspace. created_at: type: string description: Time when the skill was created. format: date-time updated_at: type: string description: Time when the skill was last updated. format: date-time created_by_id: type: string description: User ID that created the skill. updated_by_id: type: string description: User ID that last updated the skill. instructions: type: string description: Instruction body executed or reused by clients that load this skill. version: type: string description: |- Latest semver assigned by the activity log. Stamped on the document by CreateSkill / UpdateSkill so reads return it without joining workspaces.activities. securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````