/education-cloud-academic-calendar-generate

name: education-cloud-academic-calendar-generate
description: "Use this skill to set up, create, or generate an academic calendar for Education Cloud orgs. Creates Academic Year, Academic Terms (semester/quarter/trimester), Academic Sessions, registration windows, and add/drop deadlines from natural language or documents. Validates date ranges and handles overlapping sessions, linking terms to the year and sessions to their term. TRIGGER when: user asks to \"create an academic calendar\", \"set up semester dates\", \"generate the academic year\", \"add terms and sessions\", \"configure registration windows\", or \"add/drop deadlines\" — or uploads a calendar document (PDF, CSV, XLSX) containing term or session dates. DO NOT TRIGGER for querying or updating existing calendar records, scheduling courses, or configuring course offerings."
metadata:
  version: "1.0"
  domains:
    - "Education"
  minApiVersion: "68.0"
  accessCheck: "OrgPreferences.EducationCloudEnabled"
  cliTools:
    - tool: ["python3"]
      semver: ">=3.8"
  relatedSkills:
    - "education-cloud-multi-campus-configure"

Education Cloud Academic Calendar Generation

Create the foundational academic calendar infrastructure for Education Cloud orgs, parsing calendar data from documents or natural language and generating validated Academic Year, Term, and Session records with proper date ranges and institutional linkage.

Scope

• **In scope**: Academic Year records, Academic Term records (semester/quarter/trimester systems), Academic Session records (term subdivisions), registration windows, add/drop deadlines, date validation
• **Out of scope**: Course scheduling (delegate to course offering skills), individual course section dates, financial aid deadlines, exam schedules, institutional hierarchy setup (no dedicated skill exists yet for this — set up Accounts/campuses manually)

---

Execution Model

All Salesforce operations use relative-path REST calls. Do not use CLI or shell commands to reach Salesforce (`sf`, `sfdx`, `curl`); the execution environment may not provide them. This does not apply to the skill's own local validation script (`scripts/validate_calendar_dates.py`, see step 4) — that runs locally and never touches the org.

• **Record CRUD**: sObject REST — `POST /services/data/<ver>/sobjects/<Object>`, `GET /services/data/<ver>/sobjects/<Object>/<Id>`, `PATCH /services/data/<ver>/sobjects/<Object>/<Id>`
• **Schema checks**: sObject describe — `GET /services/data/<ver>/sobjects/<Object>/describe` (confirm object + field API names exist before writing).
• **SOQL `/query` is routable**: `GET /services/data/<ver>/query` with the SOQL passed as a structured `queryParams: {"q": "..."}`, NOT inlined into the URL as `?q=...` — confirmed by live test: inlining `?q=` 404s (`ROUTE_NOT_FOUND`/`NOT_FOUND`) via headless-360 dispatch, while `queryParams` reliably 200s. Use it to list-scan for existing terms/sessions, or resolve records by the runtime Id captured at create time and read them back with a direct `GET .../sobjects/<Object>/<Id>` — either is valid.
• **All IDs are runtime variables** captured from create-response `body.id` — never hardcode a literal Salesforce Id.
• **Resolve API version dynamically** — see Execution Transport below. Do not hardcode a version.

---

Required Inputs

Gather or infer before proceeding:

• **Calendar system**: Semester (Fall/Spring/Summer) or Quarter (Fall/Winter/Spring/Summer) or Trimester
• **Academic year span**: Start and end dates for the overall academic year
• **Term dates**: For each term - class start/end, registration open date, add/drop deadline
• **Session subdivisions**: Any sub-sessions within terms (e.g., Summer Session 1 and 2)

If the user provides a calendar document (PDF, CSV, spreadsheet), parse it to extract all dates. If the user provides natural language, ask for specific dates before proceeding.

Note: AcademicYear, AcademicTerm, and AcademicSession have no Account reference field — calendar records are not linked to a Business Account. Linkage is Year → Term (`AcademicYearId`) and Term → Session (`AcademicTermId`) only.

Defaults unless specified:

• Calendar system: **Semester** (Fall, Spring, Summer)
• Academic year naming: **"Academic Year YYYY-YYYY"** format
• Registration windows: **Open 3-4 months before term start**
• Add/drop deadlines: **2 weeks after term start**

---

Execution Transport

1. **Resolve API version**: `GET /services/data/` (unversioned) via headless-360 dispatch. Response is a map of endpoint paths already resolved to the org's current max version (e.g. `"limits": "/services/data/v69.0/limits"`) — not an array with a `version` field. Extract the version from any returned path (regex `v\d+\.\d+`) and use it as `<ver>` for every call below. 2. **Probe transport health**: `GET /services/data/<ver>/limits` via headless-360 dispatch. 2xx → route all calls through it. On absent/4xx/5xx → probe other available transports (other Salesforce MCP, authenticated `sf` CLI, custom MCP) with the same read, use first healthy, announce it. None healthy → stop, ask user to connect one; never fabricate.

---

Workflow

All steps are sequential. Do not skip or reorder. If blocked, stop and ask for missing context.

0. **Verify foundation prerequisites** — Follow `references/foundation_prerequisites.md`: org edition, Lightning Experience, Education Cloud license, running user's EDU access, Education Cloud Foundation enabled (self-heal via confirm-then-enable if off). Do not proceed to Step 1 until all checks pass.

1. **Confirm calendar system**

• Ask user: semester, quarter, or trimester system?
• Identify expected term names based on system type

2. **Gather calendar data**

• If user provides document (PDF, CSV, spreadsheet): parse to extract year, term, and session dates
• If user provides natural language: extract dates from description
• If insufficient detail: ask for specific dates (term start/end, registr