# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for One AI Skills API
  version: 1.0.0
extends: openapi/integration-os-ai-skills-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 27
- target: $.paths['/v1/ai-skills'].get
  update:
    x-apievangelist-phrasing:
      intent: List the AI skills in my account
      effect: read
      questions:
      - Which AI skills are available in my personal account?
      - Can I page through my own AI skills a few at a time?
      instructions:
      - text: List the AI skills in my account.
      - text: Show page {page} of my personal AI skills, {limit} per page.
        slots:
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a personal AI skill
      effect: write
      questions:
      - How do I write a new AI skill for myself with its own prompt and allowed tools?
      - Can I pick the model a personal skill runs on when I create it?
      instructions:
      - text: Create a personal skill {name} described as {description} with prompt {content}.
        slots:
          name: requestBody.name
          description: requestBody.description
          content: requestBody.content
      - text: 'Make me a skill named {name} ({description}) using model {model} and tools {allowedTools}, prompt: {content}.'
        slots:
          name: requestBody.name
          description: requestBody.description
          model: requestBody.model
          allowedTools: requestBody.allowedTools
          content: requestBody.content
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's AI skills
      effect: read
      questions:
      - Which AI skills are shared across every project in my organization?
      - Can I page through an organization's skill catalogue?
      instructions:
      - text: List the AI skills owned by organization {org_id}.
        slots:
          org_id: path.org_id
      - text: Show page {page} of org {org_id}'s skills.
        slots:
          page: query.page
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization-wide AI skill
      effect: write
      questions:
      - How do I add an AI skill that every project in my organization can use?
      - Can an organization skill be restricted to certain tools when it's created?
      instructions:
      - text: Create organization {org_id} skill {name} described as {description} with prompt {content}.
        slots:
          org_id: path.org_id
          name: requestBody.name
          description: requestBody.description
          content: requestBody.content
      - text: Add org-wide skill {name} to {org_id} ({description}), allowing tools {allowedTools}, prompt {content}.
        slots:
          name: requestBody.name
          org_id: path.org_id
          description: requestBody.description
          allowedTools: requestBody.allowedTools
          content: requestBody.content
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/projects/{project_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project's AI skills
      effect: read
      questions:
      - What AI skills are isolated to one particular project?
      - Can I list only the skills scoped to a single project rather than the whole org?
      instructions:
      - text: List the AI skills in project {project_id} of org {org_id}.
        slots:
          project_id: path.project_id
          org_id: path.org_id
      - text: Show page {page} of project {project_id} skills in organization {org_id}.
        slots:
          page: query.page
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/projects/{project_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an AI skill scoped to one project
      effect: write
      questions:
      - How do I create an AI skill that only one project can see?
      - Can I tag a project skill when I create it?
      instructions:
      - text: Create skill {name} in project {project_id}, org {org_id}, described as {description} with prompt {content}.
        slots:
          name: requestBody.name
          project_id: path.project_id
          org_id: path.org_id
          description: requestBody.description
          content: requestBody.content
      - text: 'Add project-only skill {name} to project {project_id} (org {org_id}) tagged {tags}: {description}, prompt {content}.'
        slots:
          name: requestBody.name
          project_id: path.project_id
          org_id: path.org_id
          tags: requestBody.tags
          description: requestBody.description
          content: requestBody.content
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project AI skill's details
      effect: read
      questions:
      - What prompt, tools and live version does a project skill currently have?
      - Can I view one project-scoped skill's full definition?
      instructions:
      - text: Get skill {id} in project {project_id}, org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Show the prompt and tools of project {project_id} skill {id} under organization {org_id}.
        slots:
          project_id: path.project_id
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a project AI skill's draft
      effect: write
      questions:
      - How do I edit the draft of a skill that belongs to a project?
      - Do edits to a project skill go live immediately, or only after publishing?
      instructions:
      - text: Update the draft prompt of skill {id} in project {project_id}, org {org_id}, to {content}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
          content: requestBody.content
      - text: Switch project {project_id} skill {id} draft to model {model} in organization {org_id}.
        slots:
          project_id: path.project_id
          id: path.id
          model: requestBody.model
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a project AI skill and all versions
      effect: destructive
      questions:
      - How do I permanently delete a project skill along with every version?
      - What happens to agents in the project that still call a deleted skill?
      instructions:
      - text: Delete skill {id} from project {project_id} in org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Permanently remove project {project_id} skill {id} and its versions, organization {org_id}.
        slots:
          project_id: path.project_id
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a project skill as SKILL.md
      effect: read
      questions:
      - Can I download a project skill's live version as a SKILL.md file?
      - How do I get a project-scoped skill into markdown for version control?
      instructions:
      - text: Export project {project_id} skill {id} in org {org_id} as SKILL.md.
        slots:
          project_id: path.project_id
          id: path.id
          org_id: path.org_id
      - text: Download the live markdown of skill {id} from project {project_id}, organization {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}/publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a project skill's draft as live
      effect: write
      questions:
      - How do I release the draft of a project skill as a new live version?
      - Are published versions of a project skill immutable?
      instructions:
      - text: Publish the draft of skill {id} in project {project_id}, org {org_id}.
        slots:
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Release project {project_id} skill {id} as a new live version in organization {org_id}.
        slots:
          project_id: path.project_id
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project skill's version history
      effect: read
      questions:
      - What versions has a project skill gone through?
      - Can I filter a project skill's versions by verification status?
      instructions:
      - text: List page {page} of versions for skill {id} in project {project_id}, org {org_id}.
        slots:
          page: query.page
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
      - text: Show project {project_id} skill {id} versions with status {verificationStatus}, page {page}, org {org_id}.
        slots:
          project_id: path.project_id
          id: path.id
          verificationStatus: query.verificationStatus
          page: query.page
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/projects/{project_id}/{id}/versions/{version}/yank'].post
  update:
    x-apievangelist-phrasing:
      intent: Yank a bad version of a project skill
      effect: destructive
      questions:
      - How do I roll back a bad release of a project skill in an emergency?
      - Do I have to give a reason when yanking a project skill version?
      instructions:
      - text: Yank version {version} of skill {id} in project {project_id}, org {org_id}, because {reason}.
        slots:
          version: path.version
          id: path.id
          project_id: path.project_id
          org_id: path.org_id
          reason: requestBody.reason
      - text: 'Pull project {project_id} skill {id} release {version} in organization {org_id}; reason: {reason}.'
        slots:
          project_id: path.project_id
          id: path.id
          version: path.version
          org_id: path.org_id
          reason: requestBody.reason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization AI skill's details
      effect: read
      questions:
      - What does an organization-wide skill's prompt and tool list look like?
      - Which version of an org skill is currently live?
      instructions:
      - text: Get organization {org_id} skill {id}.
        slots:
          org_id: path.org_id
          id: path.id
      - text: Show the full definition of org-wide skill {id} in {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an organization AI skill's draft
      effect: write
      questions:
      - How do I change the draft of a skill shared across my organization?
      - Can I make an organization skill public by editing it?
      instructions:
      - text: Update the draft prompt of organization {org_id} skill {id} to {content}.
        slots:
          org_id: path.org_id
          id: path.id
          content: requestBody.content
      - text: Set org-wide skill {id} in {org_id} public = {public}.
        slots:
          id: path.id
          org_id: path.org_id
          public: requestBody.public
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an organization AI skill
      effect: destructive
      questions:
      - How do I permanently remove an org-wide skill and every version of it?
      - Will agents across the organization break if I delete a shared skill?
      instructions:
      - text: Delete organization {org_id} skill {id}.
        slots:
          org_id: path.org_id
          id: path.id
      - text: Permanently remove org-wide skill {id} and its versions from {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/{id}/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export an organization skill as SKILL.md
      effect: read
      questions:
      - Can I download an organization skill's live version as markdown?
      - How do I back up a shared org skill as a SKILL.md document?
      instructions:
      - text: Export organization {org_id} skill {id} as SKILL.md.
        slots:
          org_id: path.org_id
          id: path.id
      - text: Download the live markdown of org-wide skill {id} in {org_id}.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/{id}/publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish an organization skill's draft
      effect: write
      questions:
      - How do I make my edits to an organization skill go live?
      - Does publishing an org skill create a new immutable version?
      instructions:
      - text: Publish the draft of organization {org_id} skill {id}.
        slots:
          org_id: path.org_id
          id: path.id
      - text: Release org-wide skill {id} in {org_id} as a new live version.
        slots:
          id: path.id
          org_id: path.org_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/{id}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization skill's versions
      effect: read
      questions:
      - What is the release history of a skill shared across my organization?
      - Can I list only the verified versions of an org skill?
      instructions:
      - text: List page {page} of versions for organization {org_id} skill {id}.
        slots:
          page: query.page
          org_id: path.org_id
          id: path.id
      - text: Show org-wide skill {id} versions in {org_id} with status {verificationStatus}, page {page}.
        slots:
          id: path.id
          org_id: path.org_id
          verificationStatus: query.verificationStatus
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/organizations/{org_id}/{id}/versions/{version}/yank'].post
  update:
    x-apievangelist-phrasing:
      intent: Yank a bad version of an organization skill
      effect: destructive
      questions:
      - How do I pull a broken release of an organization-wide skill?
      - Is the reason for yanking an org skill version kept for audit?
      instructions:
      - text: Yank version {version} of organization {org_id} skill {id} because {reason}.
        slots:
          version: path.version
          org_id: path.org_id
          id: path.id
          reason: requestBody.reason
      - text: 'Pull org-wide skill {id} release {version} in {org_id}; reason: {reason}.'
        slots:
          id: path.id
          version: path.version
          org_id: path.org_id
          reason: requestBody.reason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my AI skills
      effect: read
      questions:
      - What prompt, tools and published version does one of my skills have?
      - Can I look up any AI skill I own by ID alone?
      instructions:
      - text: Get AI skill {id}.
        slots:
          id: path.id
      - text: Show the metadata and current live version of my skill {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit the draft of one of my AI skills
      effect: write
      questions:
      - Will editing my skill affect agents currently running its live version?
      - How do I change the allowed tools on a personal skill's draft?
      instructions:
      - text: Update the draft prompt of my skill {id} to {content}.
        slots:
          id: path.id
          content: requestBody.content
      - text: Change personal skill {id}'s draft allowed tools to {allowedTools}.
        slots:
          id: path.id
          allowedTools: requestBody.allowedTools
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one of my AI skills
      effect: destructive
      questions:
      - How do I permanently delete a personal skill and all its versions?
      - Do agents calling my skill fail right away once it's deleted?
      instructions:
      - text: Delete AI skill {id}.
        slots:
          id: path.id
      - text: Permanently remove my skill {id} with every version.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/{id}/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export my AI skill as SKILL.md
      effect: read
      questions:
      - Can I download one of my skills as a SKILL.md file to keep in source control?
      - How do I share a personal skill outside the platform?
      instructions:
      - text: Export my skill {id} as SKILL.md.
        slots:
          id: path.id
      - text: Download the live markdown of personal skill {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/{id}/publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish my AI skill's draft as live
      effect: write
      questions:
      - How do I release my skill's draft so agents tracking latest pick it up?
      - Are agents pinned to an older version affected when I publish my skill?
      instructions:
      - text: Publish the draft of my skill {id}.
        slots:
          id: path.id
      - text: Release personal skill {id} as a new live version.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/{id}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the versions of my AI skill
      effect: read
      questions:
      - What changed across the releases of one of my skills?
      - Which version of my skill should I pin an agent to?
      instructions:
      - text: List page {page} of versions for my skill {id}.
        slots:
          page: query.page
          id: path.id
      - text: Show personal skill {id} versions with status {verificationStatus}, page {page}.
        slots:
          id: path.id
          verificationStatus: query.verificationStatus
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/ai-skills/{id}/versions/{version}/yank'].post
  update:
    x-apievangelist-phrasing:
      intent: Yank a bad version of my AI skill
      effect: destructive
      questions:
      - How do I stop a broken release of my skill from being selected as live?
      - Can I roll back my skill quickly after a bad publish?
      instructions:
      - text: Yank version {version} of my skill {id} because {reason}.
        slots:
          version: path.version
          id: path.id
          reason: requestBody.reason
      - text: 'Pull personal skill {id} release {version}; reason: {reason}.'
        slots:
          id: path.id
          version: path.version
          reason: requestBody.reason
      method: generated
      generated: '2026-10-01'