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

# Generate skill drafts

> Generate one or more skill drafts from a natural-language prompt and/or previously uploaded SOP files (`POST /v1/files`). Drafts are returned as a list and are **not** persisted — use `POST /v1/skills` to create each draft you want to keep. Requires `ep:skills:write`.



## OpenAPI

````yaml post /skills/generate
openapi: 3.0.3
info:
  version: 0.1.1
  title: Datagrid API
  description: Datagrid API
servers:
  - url: https://api.datagrid.com/v1
security:
  - BearerAuth: []
paths:
  /skills/generate:
    post:
      tags:
        - Skills
      summary: Generate skill drafts
      description: >-
        Generate one or more skill drafts from a natural-language prompt and/or
        previously uploaded SOP files (`POST /v1/files`). Drafts are returned as
        a list and are **not** persisted — use `POST /v1/skills` to create each
        draft you want to keep. Requires `ep:skills:write`.
      operationId: GenerateSkills
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSkillsRequest'
      responses:
        '200':
          description: Generated skill drafts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillDraftListResponse'
        '400':
          description: >-
            Bad request. No prompt or files provided, a `file_id` could not be
            resolved, or the model did not return usable drafts.
        '401':
          description: Unauthorized. API key is missing or invalid.
        '402':
          description: >-
            Credit limit exceeded. The organization does not have enough credits
            to perform this operation.
        '403':
          description: Forbidden. API key does not have `ep:skills:write`.
        '429':
          description: >-
            Rate limit exceeded. Check the `Retry-After` response header and
            retry after the specified number of seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '504':
          description: >-
            Gateway timeout. Skill generation did not complete within the time
            limit. Retry with a shorter prompt or fewer files.
components:
  schemas:
    GenerateSkillsRequest:
      type: object
      properties:
        prompt:
          type: string
          maxLength: 16000
          description: >-
            Natural-language description of the skill(s) to generate. At least
            one of `prompt` or `file_ids` must be non-empty.
        file_ids:
          type: array
          maxItems: 16
          items:
            type: string
          description: >-
            IDs of previously uploaded files to use as source material (e.g. SOP
            documents). Obtain file IDs via `POST /v1/files`. At least one of
            `prompt` or `file_ids` must be non-empty.
    SkillDraftListResponse:
      type: object
      required:
        - object
        - data
        - has_more
      properties:
        object:
          type: string
          enum:
            - list
          description: The object type, always 'list'.
        data:
          type: array
          items:
            $ref: '#/components/schemas/SkillDraft'
          description: >-
            Array of generated skill drafts. Pass each to `POST /v1/skills` to
            persist.
        has_more:
          type: boolean
          description: Whether there are more results. Always false for generate.
    RateLimitError:
      type: object
      description: >-
        Returned when the rate limit is exceeded. Rate limits are enforced per
        teamspace, endpoint path, and HTTP method over a 60-second sliding
        window. Each endpoint may have its own limit — check the
        X-RateLimit-Limit response header for the effective value.
      required:
        - error
        - message
        - retryable
        - status_code
      properties:
        status_code:
          type: integer
          description: The HTTP status code (429).
        statusCode:
          type: integer
          deprecated: true
          description: Deprecated. Use status_code instead.
        error:
          type: string
          enum:
            - rate_limit_exceeded
          description: The error code identifying this as a rate limit error.
        message:
          type: string
          description: A human-readable error message.
        mitigation:
          type: string
          description: Suggested action to resolve the error.
        retryable:
          type: boolean
          description: Whether the request can be retried after a delay.
        details:
          type: object
          properties:
            reason:
              type: string
              description: A detailed explanation of why the rate limit was exceeded.
    SkillDraft:
      type: object
      required:
        - object
        - name
        - slash_key
        - description
        - instructions
        - category
        - required_tools
        - preferred_tools
      properties:
        object:
          type: string
          enum:
            - skill_draft
          description: The object type, always 'skill_draft'.
        name:
          type: string
          maxLength: 255
          description: Suggested display name for the skill.
        slash_key:
          type: string
          maxLength: 31
          description: >-
            Suggested slash command key (e.g. `budget-check`). Deduplicated
            within the draft list.
        description:
          type: string
          maxLength: 500
          description: Short description shown in the skill picker.
        instructions:
          type: string
          maxLength: 32000
          description: The full instructions / system prompt for this skill.
        category:
          type: string
          enum:
            - document_analysis
            - construction_project_management
            - financial_analysis
            - estimation
            - quality_and_safety
            - scheduling
            - contracts_and_legal
            - data_and_reporting
            - research
            - communication
            - general_productivity
          description: Category bucket for grouping in the skill picker.
        required_tools:
          type: array
          items:
            type: string
          description: Tool identifiers that this skill requires to function.
        preferred_tools:
          type: array
          items:
            type: string
          description: Tool identifiers that this skill works best with.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````