feat: add onboarding skills

[ninja-shreyash]

Summary

Claude Code skills that automate onboarding new API endpoints to the SDK. Handles Jira ticket parsing, live API inspection, implementation, E2E browser validation, Cloudflare Workers whitelisting, and PR creation.

Supports both direct API methods (one endpoint → one SDK method) and composite methods (multiple chained API calls → one SDK method, e.g. Python SDK's extract_output).

Skills Added

Skill	Standalone?	Purpose
onboard-api	Yes	Full onboarding lifecycle — input collection → PAT + curl → design → implement → test → E2E → Cloudflare → PR. Internally invokes sdk-verify (Steps 5-6) and sdk-ship (Steps 7-8) as sub-skills.
sdk-verify	Yes	Run typecheck, lint, unit tests, build, and E2E browser validation. Reports errors without fixing. Called by onboard-api after implementation, but can also be invoked standalone after any SDK code change (e.g., /sdk-verify, "verify my changes", "run e2e").
sdk-ship	Yes	Commit, Cloudflare whitelist, and PR creation/update with structured description template. Called by onboard-api after verification passes, but can also be invoked standalone to ship any SDK changes (e.g., /sdk-ship, "raise PR", "ship it").

Skill invocation flow

/onboard-api PLT-99452
  │
  ├─ Steps 1-4: Input → Curl → Design → Implement  (onboard-api handles directly)
  │
  ├─ Steps 5-6: Verify & E2E ──────────────────────→ invokes sdk-verify
  │     └─ Fix loop: if failures → fix → re-invoke sdk-verify
  │
  └─ Steps 7-8: Cloudflare + Commit + PR ──────────→ invokes sdk-ship

Each sub-skill can also be used independently:

# After making manual SDK changes
/sdk-verify              # typecheck + lint + test + build + E2E

# After verification passes
/sdk-ship                # commit + Cloudflare + PR

How to use

# From Jira ticket
/onboard-api PLT-99452

# From Swagger URL
/onboard-api Swagger: https://alpha.uipath.com/orchestrator_/swagger/v17.0/swagger.json Endpoint: GET /odata/Jobs

# Add method to existing service
/onboard-api Add getById to Jobs. Swagger: <url> Endpoint: GET /odata/Jobs({key})

Requires .env in repo root:

PAT_TOKEN=rt_...
BASE_URL=https://alpha.uipath.com
ORG_NAME=popoc
TENANT_NAME=adetenant

What onboard-api does (8 steps)

1. Collect input & branch — Jira ticket parsing or direct Swagger URL + endpoints. Detects ticket type (Direct API vs Composite with/without reference). Scope-checks to avoid onboarding already-implemented endpoints.
2. PAT + curl live API — Reads token from .env, curls actual endpoints. Won't proceed without a real response. For composite methods, curls ALL underlying endpoints.
3. Design decisions — Decision trees for response shape (drop/rename/reshape/enrich), service placement (Pattern A/B/C), method binding, transform pipeline. For composite methods: flow decomposition, composition pattern (Sequential/Conditional/Parallel/Fan-out), error handling strategy (propagate vs degrade), response composition.
4. Implement — Types, constants, models, service class, endpoints, pagination, exports, unit tests, integration tests, JSDoc, doc updates. Composite methods get private helpers per API call + @track on public method only.
5. Verify — Invokes sdk-verify: typecheck, lint, test:unit, build, E2E browser validation
6. E2E validate — Part of sdk-verify: packs SDK tarball, scaffolds temp React app with PAT auth + Vite proxy, validates in browser, deletes everything after
7. CF Workers whitelist — Part of sdk-ship: adds endpoint regex to apps-dev-tools proxy, runs tests, raises separate PR. For composite methods, whitelists ALL internal endpoints.
8. Commit & PR — Part of sdk-ship: pushes branch, creates PR with structured description (Method Added, Endpoint Called, Example Usage, API Response vs SDK Response, Files)

Ticket type detection

Pattern in Jira description	Type
API: field present	Direct API
Reference: + Method: fields	Composite with reference (e.g., Python SDK method)
Flow: block present	Composite without reference
Both Reference: and Flow:	Reference is primary, flow is supplementary

Agent docs enhancements

Learnings from running the skills on real onboarding tasks (PLT-100298) were fed back into agent_docs/:

conventions.md

• Required vs optional folderId — Documents two patterns for folder-scoped services. Required folderId as positional param (Assets, Queues, Buckets) vs optional in options (Jobs). Both use unconditional createHeaders() since the utility filters undefined automatically.

rules.md

• JSDoc: expand examples — When a method supports expand, show multiple expandable entities in @example (e.g., expand: 'Robot,Machine,Release')
• JSDoc: descriptive context — Add a one-line description of what the response includes beyond the method signature
• Unit tests: domain-specific error constants — Use domain-specific constants for entity-specific methods (e.g., getById → ERROR_JOB_NOT_FOUND), generic for collection methods (getAll). Matches existing Assets/Queues/Jobs pattern.
• Unit tests: transform completeness — Verify both camelCase presence AND PascalCase absence. Existing pattern in Assets (assets.test.ts:94), Queues (queues.test.ts:88), ChoiceSets (choicesets.test.ts:243).
• Integration tests: transform validation — New guidance to include a dedicated transform validation test against the live API. Notes this extends the existing unit test pattern.

Reference files

File	What's in it
references/onboarding.md	Design decision trees, field filtering/renaming/reshaping/enrichment examples, service placement patterns (A/B/C) with build system wiring, method binding code examples
references/composite-methods.md	Composition patterns (Sequential/Conditional/Parallel/Fan-out), error handling strategies (propagate vs degrade), response composition, private helper structure, testing patterns
references/e2e-testing.md	Full React app scaffold, Vite proxy config, PAT auth hook, component generation, SDK initialization rules, gotchas from real runs
references/cloudflare-whitelist.md	Regex patterns for CF Workers proxy, base constants, test structure

Files

Area	Files
Skills	.claude/skills/onboard-api/SKILL.md
Skill references	.claude/skills/onboard-api/references/onboarding.md, composite-methods.md, e2e-testing.md, cloudflare-whitelist.md
Verify skill	.claude/skills/sdk-verify/SKILL.md
Ship skill	.claude/skills/sdk-ship/SKILL.md
Agent docs	agent_docs/conventions.md, agent_docs/rules.md

Real output

• PR feat(orchestrator): add Jobs getAll service [PLT-99452] #290 — Generated from Jira ticket PLT-99452 (Direct API): Jobs.getAll() with FolderScopedService, OData pagination, field mapping, types, unit tests, integration tests, build wiring, doc updates.
• PR feat(jobs): onboard getOutput method [PLT-100430] #320 — Generated from Jira ticket PLT-100430 (Composite): Jobs.getOutput() with conditional composition (inline vs file-based output), Attachments API blob download, private helpers, 10 unit tests, integration tests.

Test plan

• Invoke /onboard-api with a Direct API Jira ticket and verify full workflow completes (PLT-99452 → PR feat(orchestrator): add Jobs getAll service [PLT-99452] #290)
• Invoke /onboard-api with a Composite Jira ticket and verify full workflow completes (PLT-100430 → PR feat(jobs): onboard getOutput method [PLT-100430] #320)
• Invoke with direct Swagger URL + endpoint
• Verify E2E app scaffolds and runs correctly
• Verify CF Workers PR gets created in apps-dev-tools
• Verify agent_docs enhancements match actual codebase patterns

🤖 Auto-generated using onboarding skills

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud