> ## Documentation Index > Fetch the complete documentation index at: https://docs.parley.so/llms.txt > Use this file to discover all available pages before exploring further. # Update a skill > Replace a skill's SKILL.md (content) or everything it holds (uploadId), change when it's used, or turn it on or off. Omitted fields are left unchanged. A skill's slug and scope can't change. Returns 400 INVALID_REFERENCE when uploadId isn't an upload or nothing was uploaded to it, and 400 INVALID_SKILL when the SKILL.md or archive can't be read. ## OpenAPI ````yaml https://api.parley.so/openapi.json patch /skills/{slug} openapi: 3.1.1 info: title: Parley API version: 1.0.0 description: >- Manage Parley's projects (matters or cases), accounts (client organizations), contacts (people), tasks, custom fields, notes, files, activity, automations, and skills. Records refer to each other as { type, id, name } references; writes take IDs. Errors are { error: { code, message, details } }, where code names what went wrong and each operation lists the codes it can return. In a query string, write a timestamp's offset as Z or %2B, because a raw + arrives as a space. The MCP server at /mcp offers the same data as a smaller set of tools. servers: - url: https://api.parley.so/v1 security: - bearerAuth: [] tags: - name: Projects description: >- A project is a matter or case: it groups the files, notes, activity, and tasks for one engagement, and links to the accounts and contacts it involves. - name: Accounts description: >- An account is a client organization. Contacts belong to it, and projects link to it. - name: Contacts description: >- A contact is a person, optionally belonging to one account and linked to projects. - name: Tasks description: >- A task is a to-do with a status, assignee, and due date, optionally about one project, account, or contact. - name: Fields description: >- Custom fields defined for projects, accounts, contacts, or tasks. Records carry their values in fields, keyed by field name. - name: Notes description: >- Markdown notes on a project, account, or contact. Updates take the version you last read, so concurrent edits fail with 409 VERSION_CONFLICT instead of overwriting. - name: Files description: >- Files and folders of a project, account, contact, or intake, or the organization's Library. Add a file by creating an upload, PUTting its bytes, and adding the upload to a location. - name: Activity description: >- What happened across the organization or on one record: changes, links, notes, files, USCIS case updates, and synced emails and meetings. Each item's kind says which details it carries. - name: Sessions description: >- Conversations with Parley's assistant, from the web app, Word, Outlook, automation runs, and the API. Start one with a message, follow up or steer it while it works, and read its replies. - name: Automations description: >- Instructions Parley's assistant carries out on a schedule, as the person who created them, with nobody present. - name: Skills description: >- Reusable playbooks for Parley's assistant: a SKILL.md plus optional bundled documents, addressed by slug. - name: Users description: The people in your organization, and the caller. paths: /skills/{slug}: patch: tags: - Skills summary: Update a skill description: >- Replace a skill's SKILL.md (content) or everything it holds (uploadId), change when it's used, or turn it on or off. Omitted fields are left unchanged. A skill's slug and scope can't change. Returns 400 INVALID_REFERENCE when uploadId isn't an upload or nothing was uploaded to it, and 400 INVALID_SKILL when the SKILL.md or archive can't be read. operationId: updateSkill parameters: - name: slug in: path required: true schema: type: string maxLength: 64 pattern: ^[a-z0-9][a-z0-9-]*$ description: The skill's slug. requestBody: required: false content: application/json: schema: type: object properties: content: type: string maxLength: 100000 description: >- The skill's SKILL.md, which replaces the current one and keeps the bundled documents: YAML frontmatter with a name (up to 120 characters) and a description (up to 2,000), then the instructions in markdown, 100,000 characters in all. For an auto skill, the description is what the assistant matches tasks against, so say when to use it. Refer to a bundled document by its path, such as references/engagement-letter.docx. uploadId: type: string minLength: 1 description: >- The id of an upload, once its bytes have been PUT to its url, holding the whole skill, which replaces everything it holds: a .skill or .zip archive with SKILL.md at its root or inside one top-level folder, plus any documents under references/ (pdf, doc, docx, md, txt, json, csv, html, pptx, xls, xlsx; up to 100 files and 25 MB), or a single .md file used as SKILL.md. A manifest.yaml in the archive is ignored. activation: enum: - auto - on-demand type: string description: >- When the skill is used. auto: Parley's assistant uses it whenever its description fits the task. on-demand: only when someone runs it, from a project's Run Skill list or by typing / in a message. enabled: type: boolean description: Turn the skill on or off. additionalProperties: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Skill' '400': description: >- The request was invalid. VALIDATION_FAILED, INVALID_REFERENCE, INVALID_SKILL. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationFailedError' - $ref: '#/components/schemas/InvalidReferenceError' - $ref: '#/components/schemas/InvalidSkillError' '401': description: Missing or invalid credentials. UNAUTHORIZED. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: You don't have permission. FORBIDDEN. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Not found. NOT_FOUND. content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '429': description: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsError' components: schemas: Skill: type: object properties: id: type: string minLength: 1 description: The skill ID. slug: type: string description: >- The skill's folder name, chosen when the skill is created. It is how the skill is addressed, and the name the assistant loads it by. name: type: string description: The skill name, from its SKILL.md. description: type: string description: What the skill is for, from its SKILL.md. scope: enum: - organization - personal type: string description: >- Who can use the skill. organization: everyone in the organization. personal: only the person who created it. activation: enum: - auto - on-demand type: string description: >- When the skill is used. auto: Parley's assistant uses it whenever its description fits the task. on-demand: only when someone runs it, from a project's Run Skill list or by typing / in a message. enabled: type: boolean description: Whether the skill is on. Parley never uses a skill that is off. createdAt: type: string format: date-time description: When the skill was created. updatedAt: type: string format: date-time description: When the skill was last changed. required: - id - slug - name - description - scope - activation - enabled - createdAt - updatedAt ValidationFailedError: type: object properties: error: type: object properties: code: type: string const: VALIDATION_FAILED message: type: string examples: - The request is invalid. details: type: object properties: issues: type: array items: type: object properties: path: type: string description: >- Where the problem is, as a dotted path into the input such as accountIds.add.0 or reminder.remindAt. Empty for the input as a whole. message: type: string description: What is wrong with the value. required: - path - message description: Each problem with the input. required: - issues required: - code - message - details required: - error InvalidReferenceError: type: object properties: error: type: object properties: code: type: string const: INVALID_REFERENCE message: type: string examples: - >- The request refers to a record or user that doesn't exist or that you can't use. details: type: object properties: field: type: string description: The input that holds the reference, such as accountIds. ids: type: array items: type: string description: The IDs that could not be used. required: - field - ids required: - code - message - details required: - error InvalidSkillError: type: object properties: error: type: object properties: code: type: string const: INVALID_SKILL message: type: string examples: - The skill could not be read. required: - code - message required: - error UnauthorizedError: type: object properties: error: type: object properties: code: type: string const: UNAUTHORIZED message: type: string examples: - Missing or invalid credentials. required: - code - message required: - error ForbiddenError: type: object properties: error: type: object properties: code: type: string const: FORBIDDEN message: type: string examples: - You don't have permission to do this. required: - code - message required: - error NotFoundError: type: object properties: error: type: object properties: code: type: string const: NOT_FOUND message: type: string examples: - Not found. required: - code - message required: - error TooManyRequestsError: type: object properties: error: type: object properties: code: type: string const: TOO_MANY_REQUESTS message: type: string examples: - Too many requests. required: - code - message required: - error securitySchemes: bearerAuth: type: http scheme: bearer description: A Parley API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.