> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Attach a skill to a workspace



## OpenAPI

````yaml /api-reference/openapi.yaml post /workspaces/{workspace_id_or_name}/workspace_skills
openapi: 3.0.3
info:
  title: Guild Public API
  version: 1.0.0
  description: >-
    The Guild public API, served at https://api.guild.ai/v1. Authenticate with
    an account API key, sent as HTTP Basic (key id as the username, secret as
    the password) or as a Bearer token `<key id>:<secret>`, or with an OAuth 2.0
    access token. Each operation lists the credentials it accepts and the scopes
    it needs; see https://docs.guild.ai/api-reference/introduction#scopes.
    Versions are path integers and v1 is the only one: a breaking change ships
    as a new version rather than changing v1. Lists page with `limit` and
    `offset` and report `pagination.has_more`. A session-events websocket also
    exists at wss://api.guild.ai/v1/sessions/{session_id}/events/ws with the
    same credentials on the handshake; OpenAPI cannot describe websockets, so it
    is not listed in paths.
servers:
  - url: https://api.guild.ai/v1
    description: Production
security: []
tags:
  - name: accounts
  - name: agents
  - name: integrations
  - name: other
  - name: sessions
  - name: skills
  - name: triggers
  - name: workspaces
paths:
  /workspaces/{workspace_id_or_name}/workspace_skills:
    post:
      tags:
        - workspaces
      summary: Attach a skill to a workspace
      operationId: add_workspace_skill
      parameters:
        - name: workspace_id_or_name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                skill_id:
                  format: uuid
                  title: Skill Id
                  type: string
              required:
                - skill_id
              title: AddWorkspaceSkillInput
              type: object
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceSkill'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - apiKey: []
        - bearerApiKey: []
        - oauth2:
            - workspaces:write
            - skills:read
components:
  schemas:
    WorkspaceSkill:
      type: object
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        creator_id:
          type: string
          format: uuid
          description: The user or API key that added this skill to the workspace.
        skill_id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
        archived_at:
          type: string
          format: date-time
          nullable: true
        archived_by_id:
          type: string
          format: uuid
          nullable: true
        creator: {}
        skill: {}
        type: {}
        workspace: {}
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: basic
      description: >-
        API key: key id as the username, secret as the password. An account API
        key carries the same scopes as an OAuth token and is checked against the
        scopes listed under oauth2 on each operation. A trigger API key is
        limited to its trigger's workspace and reaches only the session
        operations that list this scheme alongside the oauth2 scopes.
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: <key id>:<secret>
      description: >-
        The same API key as one Bearer token, `<key id>:<secret>`. An account
        API key carries the same scopes as an OAuth token and is checked against
        the scopes listed under oauth2 on each operation. A trigger API key is
        limited to its trigger's workspace and reaches only the session
        operations that list this scheme alongside the oauth2 scopes.
    oauth2:
      type: oauth2
      description: >-
        OAuth 2.0 authorization code flow with PKCE (S256). Discovery:
        https://api.guild.ai/.well-known/oauth-authorization-server.
      flows:
        authorizationCode:
          authorizationUrl: https://api.guild.ai/v1/oauth/authorize
          tokenUrl: https://api.guild.ai/v1/oauth/token
          refreshUrl: https://api.guild.ai/v1/oauth/token
          scopes:
            agents:read: Read agents
            agents:write: Read and change agents
            sessions:read: Read sessions
            sessions:write: Read and change sessions
            workspaces:read: Read workspaces
            workspaces:write: Read and change workspaces
            skills:read: Read skills
            skills:write: Read and change skills
            integrations:read: Read integrations
            integrations:write: Read and change integrations
            applications:read: Read applications
            applications:write: Read and change applications
            organizations:read: Read organizations
            organizations:write: Read and change organizations

````