> ## 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.

# Skills SDK Reference

> SDK reference for the Skills API, available in Node.js and Python.

## Skills

### List Skills

Returns the skills visible to the current workspace, ordered by creation time with the newest skill first. Use `starting_after` or `ending_before` to page through large collections.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.skills.list()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.skills.list();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": str,
        "data": {
            "skill_id": str,
            "display_name": str,
            "description": str,
            "tags": List[str],
            "project_id": str,
            "path": str,
            "created_at": date,
            "updated_at": date,
            "created_by_id": str,
            "updated_by_id": str,
            "instructions": str,
            "version": str,
        },
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        skillId: string;
        displayName: string;
        description: string;
        tags: string[];
        projectId: string;
        path: string;
        createdAt: Date;
        updatedAt: Date;
        createdById: string;
        updatedById: string;
        instructions: string;
        version: string;
      };
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create a Skill

Creates a reusable skill in the workspace. Skills store instructions, metadata, and an optional project location so teams can standardize repeatable AI workflows.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.skills.create(request={
          "display_name": "Josefina_Conn",
          "project_id": "<id>",
      })

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.skills.create({
      displayName: "Josefina_Conn",
      projectId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "display_name": str,  # required
        "description": Optional[str],
        "tags": List[str],
        "path": str,  # required
        "project_id": Optional[str],
        "instructions": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      display_name: string;  // required
      description?: string | undefined;
      tags?: string[];
      path: string;  // required
      project_id?: string | undefined;
      instructions?: string | undefined;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "skill": {
            "skill_id": str,
            "display_name": str,
            "description": str,
            "tags": List[str],
            "project_id": str,
            "path": str,
            "created_at": date,
            "updated_at": date,
            "created_by_id": str,
            "updated_by_id": str,
            "instructions": str,
            "version": str,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      skill: {
        skillId: string;
        displayName: string;
        description: string;
        tags: string[];
        projectId: string;
        path: string;
        createdAt: Date;
        updatedAt: Date;
        createdById: string;
        updatedById: string;
        instructions: string;
        version: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Skill

Retrieves an existing skill by skill ID. Display names are also accepted for compatibility because they are unique within a workspace.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.skills.get(skill_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.skills.get({
      skillId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "skill_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      skillId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "skill": {
            "skill_id": str,
            "display_name": str,
            "description": str,
            "tags": List[str],
            "project_id": str,
            "path": str,
            "created_at": date,
            "updated_at": date,
            "created_by_id": str,
            "updated_by_id": str,
            "instructions": str,
            "version": str,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      skill: {
        skillId: string;
        displayName: string;
        description: string;
        tags: string[];
        projectId: string;
        path: string;
        createdAt: Date;
        updatedAt: Date;
        createdById: string;
        updatedById: string;
        instructions: string;
        version: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a Skill

Deletes a skill from the workspace. The response body is empty when the delete succeeds.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.skills.delete(skill_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.skills.delete({
      skillId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "skill_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      skillId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### 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.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.skills.update(skill_id="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.skills.update({
      skillId: "<id>",
      updateSkillRequest: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "skill_id": str,  # required
        "display_name": Optional[str],
        "description": Optional[str],
        "tags": List[str],
        "path": Optional[str],
        "instructions": Optional[str],
        "project_id": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      skillId: string;  // required
      updateSkillRequest: {  // required
        displayName?: string;
        description?: string;
        tags?: string[];
        path?: string;
        instructions?: string;
        projectId?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "skill": {
            "skill_id": str,
            "display_name": str,
            "description": str,
            "tags": List[str],
            "project_id": str,
            "path": str,
            "created_at": date,
            "updated_at": date,
            "created_by_id": str,
            "updated_by_id": str,
            "instructions": str,
            "version": str,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      skill: {
        skillId: string;
        displayName: string;
        description: string;
        tags: string[];
        projectId: string;
        path: string;
        createdAt: Date;
        updatedAt: Date;
        createdById: string;
        updatedById: string;
        instructions: string;
        version: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>