openapi: 3.1.0
info:
  title: Legal Ed Skills Hub
  description: Progressively discover and load pedagogical AI skills for legal education.
    Start with the personas list, drill into a persona for its skill inventory, then
    fetch individual skill instructions and reference materials as needed.
  version: 1.0.0
servers:
- url: https://harvard-lil.github.io/lawskills-hub
paths:
  /actions/personas.json:
    get:
      operationId: listPersonas
      summary: List all available personas
      description: Returns a lightweight index of all personas in the Legal Ed Skills
        Hub. Each entry includes the persona id, display label, headline, and number
        of skills. Use a persona id to fetch its full detail.
      responses:
        '200':
          description: Persona index
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonaIndex'
  /actions/personas/{persona_id}.json:
    get:
      operationId: getPersona
      summary: Get full detail for one persona
      description: Returns a persona's design principles, pedagogical objective, tone,
        and a list of available skills with descriptions. Use a skill name to fetch
        its full instructions.
      parameters:
      - name: persona_id
        in: path
        required: true
        schema:
          type: string
          enum: &id001
          - professor
          - student
          - pro-se
          - cle
          - skill-developer
        description: Persona identifier
      responses:
        '200':
          description: Persona detail with skill listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonaDetail'
  /actions/skills/{persona_id}/{skill_name}.json:
    get:
      operationId: getSkill
      summary: Get full skill instructions
      description: Returns the complete skill instructions (the SKILL.md body) for
        one skill, plus metadata and a list of available reference documents. Follow
        the skill_body instructions to assist the user.
      parameters:
      - name: persona_id
        in: path
        required: true
        schema:
          type: string
          enum: *id001
        description: Persona identifier
      - name: skill_name
        in: path
        required: true
        schema:
          type: string
          enum:
          - client-email-coach
          - development-plan
          - exam-answer-eval
          - feedback-coach
          - issue-interview
          - research-coach
          - skill-creator
          - skill-reviewer
          - skill-tester
          - socratic-tutor
          - syllabus-evidence-based
          - syllabus-traditional
          - topic-curriculum
          - understanding-check
        description: Skill name (unique within a persona)
      responses:
        '200':
          description: Full skill content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkillDetail'
  /actions/skills/{persona_id}/{skill_name}/references/{ref_name}.json:
    get:
      operationId: getReference
      summary: Get a skill's reference document
      description: Returns the content of a reference markdown document that accompanies
        a skill. Only fetch when the skill instructions direct you to.
      parameters:
      - name: persona_id
        in: path
        required: true
        schema:
          type: string
          enum: *id001
        description: Persona identifier
      - name: skill_name
        in: path
        required: true
        schema:
          type: string
          enum:
          - client-email-coach
          - development-plan
          - exam-answer-eval
          - feedback-coach
          - issue-interview
          - research-coach
          - skill-creator
          - skill-reviewer
          - skill-tester
          - socratic-tutor
          - syllabus-evidence-based
          - syllabus-traditional
          - topic-curriculum
          - understanding-check
        description: Skill name (unique within a persona)
      - name: ref_name
        in: path
        required: true
        schema:
          type: string
          enum:
          - rubric-schema
          - syllabus-research-protocol
        description: Reference document name (without .md extension)
      responses:
        '200':
          description: Reference document content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReferenceDetail'
components:
  schemas:
    PersonaIndex:
      type: object
      properties:
        description:
          type: string
        personas:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Persona identifier
              label:
                type: string
                description: Display name
              description:
                type: string
                description: 'When this persona applies: describes the type of user
                  and tasks this persona handles. Use this to match against the user''s
                  question.'
              objective:
                type: string
                description: The persona's core pedagogical objective and constraint
              skill_count:
                type: integer
                description: Number of available skills
    PersonaDetail:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        headline:
          type: string
        pitch:
          type: string
        design:
          type: object
          description: 'Pedagogical design: objective, principles, tone, success criteria'
          properties:
            objective:
              type: string
            principles:
              type: array
              items:
                type: string
            tone:
              type: string
            success:
              type: string
        skills:
          type: array
          description: Available skills — fetch one by name to get full instructions
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              version:
                type: string
              status:
                type: string
                enum:
                - preview
                - official
                description: Release status of the skill
              has_references:
                type: boolean
              reference_count:
                type: integer
        usage_hint:
          type: string
    SkillDetail:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        version:
          type: string
        status:
          type: string
          enum:
          - preview
          - official
          description: Release status of the skill
        persona:
          type: string
        skill_body:
          type: string
          description: Complete skill instructions in markdown. Follow these to assist
            the user.
        references:
          type: array
          description: Reference documents available for this skill
          items:
            type: object
            properties:
              name:
                type: string
              fetch_path:
                type: string
                description: Path to fetch reference content
        usage_hint:
          type: string
    ReferenceDetail:
      type: object
      properties:
        name:
          type: string
        skill:
          type: string
        persona:
          type: string
        content:
          type: string
          description: Full markdown content of the reference document