> ## Documentation Index > Fetch the complete documentation index at: https://docs.hq.zone/llms.txt > Use this file to discover all available pages before exploring further. # Upload a skill > Creates a workspace-owned skill from caller-supplied content. The body may be either inline markdown (wrapped automatically as SKILL.md) or a multi-file pack of base64-encoded files that must include a SKILL.md at the root. The display name must be 3 to 60 characters of letters, digits, spaces, hyphens, or underscores and is used to derive the slug; an optional runtime profile (claude-sdk, hermes, or openai-agents; defaults to claude-sdk) and an optional capability slot may be set. Size limits apply (up to 50 files, 256 KiB total raw content, 64 KiB markdown, and a 1 MB request limit). Re-uploading with the same derived slug updates the existing skill in place. Returns the resulting slug and version with HTTP 201. Admin only; scoped to the caller's own workspace. ## OpenAPI ````yaml POST /v1/skills/upload openapi: 3.1.0 info: title: HQ API description: >- Public HTTP API for HQ. Authenticate with a Personal Access Token (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's behalf. Both grant from the same resource:action scope vocabulary; an endpoint's required scope is listed under its `security`. license: name: Apache-2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://api.hq.zone description: HQ API (production) security: [] tags: - name: me description: The signed-in user's own account - name: conversations description: Conversations and their messages - name: documents description: The content-addressed documents library - name: schedules description: Scheduled prompts and recurring tasks - name: agents description: Agents, their skills and integrations - name: memory description: What the assistant remembers (L5 governance) - name: tokens description: Personal Access Token management - name: billing description: Usage and billing - name: notifications description: In-app notification center - name: admin description: Workspace administration - name: integrations description: Workspace integrations (Slack, MCP, skills) - name: onboarding description: New-workspace onboarding wizard - name: auth description: Sign-in, sessions, and OAuth paths: /v1/skills/upload: post: tags: - integrations summary: Upload a skill description: >- Creates a workspace-owned skill from caller-supplied content. The body may be either inline markdown (wrapped automatically as SKILL.md) or a multi-file pack of base64-encoded files that must include a SKILL.md at the root. The display name must be 3 to 60 characters of letters, digits, spaces, hyphens, or underscores and is used to derive the slug; an optional runtime profile (claude-sdk, hermes, or openai-agents; defaults to claude-sdk) and an optional capability slot may be set. Size limits apply (up to 50 files, 256 KiB total raw content, 64 KiB markdown, and a 1 MB request limit). Re-uploading with the same derived slug updates the existing skill in place. Returns the resulting slug and version with HTTP 201. Admin only; scoped to the caller's own workspace. operationId: upload_skill requestBody: content: application/json: schema: $ref: '#/components/schemas/SkillUploadReq' required: true responses: '201': description: Workspace skill created content: application/json: schema: $ref: '#/components/schemas/SkillUploadResp' '400': description: Invalid pack '403': description: Admin role required security: - bearer_pat: - admin - oauth2: - admin components: schemas: SkillUploadReq: allOf: - $ref: '#/components/schemas/UploadBody' - type: object required: - name properties: description: type: - string - 'null' description: One-line description shown on the Skills page. name: type: string description: |- Display name (3–60 chars, alphanumeric + spaces/hyphens). Used to derive the slug. profile: type: - string - 'null' description: Runtime profile this pack targets. Defaults to `claude-sdk`. provides: type: - string - 'null' description: >- Capability slot this skill fills, e.g. `app-design`. When set (and the skill is enabled), it supersedes the platform default that provides the same capability for this workspace - the tenant's own instructions replace ours. Brand tokens still flow via the workspace preamble, independent of which design skill is active. SkillUploadResp: type: object required: - slug - version properties: slug: type: string version: type: string UploadBody: oneOf: - type: object description: |- Inline markdown: server wraps it as `SKILL.md` in a single-file tarball. Covers the "paste a paragraph or two" case. required: - body_markdown - kind properties: body_markdown: type: string kind: type: string enum: - markdown - type: object description: |- Multi-file pack: caller supplies the directory contents as a list of (path, base64) entries. Must include exactly one `SKILL.md` at the root. required: - files - kind properties: files: type: array items: $ref: '#/components/schemas/UploadFile' kind: type: string enum: - files UploadFile: type: object required: - path - content_base64 properties: content_base64: type: string description: |- Standard base64 (no URL-safe variant) of the file's bytes. Keep payloads small - combined raw size is capped at 256 KiB. path: type: string description: |- Relative path inside the pack (e.g. `SKILL.md`, `examples/x.md`). Forward slashes only; no leading slash, no `..` segments. securitySchemes: bearer_pat: type: http scheme: bearer bearerFormat: hq_pat description: 'Personal Access Token. Send as `Authorization: Bearer hq_pat_...`.' oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://app.hq.zone/v1/oauth/authorize tokenUrl: https://api.hq.zone/v1/oauth/token refreshUrl: https://api.hq.zone/v1/oauth/token scopes: admin: Administer the workspace (users, settings, integrations) agents:read: View the agents in your workspace agents:write: Create and configure agents billing:read: View usage and billing information conversations:read: Read your conversations and their messages conversations:write: Start conversations and send messages on your behalf documents:read: Read your documents library documents:write: Upload and manage documents in your library memory:read: Read what the assistant remembers about you memory:write: Correct or delete what the assistant remembers schedules:read: View your scheduled tasks schedules:write: Create and manage scheduled tasks tables:read: Read your tables and their rows tables:write: Create tables and add, edit, or delete rows ````