feat: add onboarding skills

[ninja-shreyash]

Summary

Two Claude Code skills that automate onboarding new API endpoints into the UiPath TypeScript SDK. Together they handle the full lifecycle: input collection → live API inspection → code generation → testing → E2E validation → Cloudflare Workers whitelisting → commit → PR.

---

Skills Overview

onboard-api — Orchestrator Skill

Thin orchestrator that collects input and manages the git workflow. Does not implement anything — delegates all coding to sdk-service-dev.

Use for any SDK service work that involves adding endpoints — whether it's a brand new service or adding a method to an existing one.

Accepts two input paths:

Input	How it works
Jira ticket (e.g., PLT-99452)	Fetches the ticket via Atlassian MCP, extracts Swagger URL, endpoint paths, OAuth scopes from the description
Direct input (Swagger URL + endpoints)	Parses the URL and endpoint list directly

What it does:

1. Collects & validates input (Swagger URL, endpoints, OAuth scopes)
2. Creates a feature branch (feat/sdk-<ticket-key> or feat/<service>-<method>)
3. Invokes sdk-service-dev for all implementation work
4. Whitelists new endpoints in the Cloudflare Workers proxy (apps-dev-tools repo) — raises a separate PR there
5. Commits all SDK changes and raises a PR

Files:

• .claude/skills/onboard-api/SKILL.md — main skill
• .claude/skills/onboard-api/references/cloudflare-whitelist.md — Cloudflare Workers whitelisting procedure

---

sdk-service-dev — Implementation Engine

The heavy lifter. Codifies every repo convention into executable decision trees and checklists. Called by onboard-api for implementation — not invoked directly for adding endpoints (use onboard-api instead, which handles the full git workflow around it).

Use sdk-service-dev directly only for non-onboarding work: bug fixes, refactoring, reviewing code, updating tests, or general repo modifications where there's no Swagger spec or endpoint to onboard.

What it covers:

Area	What it enforces
Step 0: PAT + curl	Reads .env.skills, curls live endpoints before writing any code. Blocks if token missing or API errors.
SDK response design	Inspects real API response → decides what to drop, rename, reshape, or enrich
Service placement	Decision tree: hierarchical sub-service vs domain-grouped vs independent root
Method binding	Binds state-changing ops to response objects so developers don't pass IDs around
Transforms	4-step pipeline, each step justified by the actual API response shape
Pagination	OData offset vs continuation token, conditional return types
Type naming	{Entity}GetResponse, Raw{Entity}GetResponse, {Entity}GetAllOptions — strict patterns
BaseService vs FolderScopedService	Decision tree based on header requirements
Testing	Unit tests (vitest), integration tests (live API), E2E validation (temp React app)
Documentation	JSDoc on service model, oauth-scopes.md, pagination.md, mkdocs.yml
NEVER Do list	30+ anti-patterns that have caused rejected PRs, with explanations

Reference docs in sdk-service-dev/references/:

File	Contents
onboarding.md	Full onboarding walkthrough — API inspection, response design (field filtering, renaming, reshaping, enrichment), service placement patterns (A/B/C), method binding DX philosophy, build system wiring
transforms.md	Response transformation pipeline steps, standard field renames, OData prefix pattern, outbound transforms
pagination.md	Offset vs token pagination, constant definitions, excludeFromPrefix rules, conditional return types
testing.md	Unit test setup (vitest + mocks), integration test rules (guard clauses, cleanup, error handling)
e2e-testing.md	Ephemeral React app workflow — build SDK → pack tarball → scaffold temp app → generate test component → validate in browser → delete everything
jsdoc.md	JSDoc conventions, telemetry decorators, required doc file updates per PR

---

Setup

Prerequisites

1. .env.skills file in the repo root (gitignored):

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

The PAT token is used for:

• Step 0 (curl): Calling live API endpoints to inspect real responses before designing types
• E2E validation: The temp React app uses it for PAT/secret-based auth (no OAuth flow needed)

To get a PAT: UiPath Automation Cloud → Admin → Access Tokens → Generate Personal Access Token

2. gh CLI authenticated (for raising PRs in both uipath-typescript and apps-dev-tools)

3. apps-dev-tools repo as an additional working directory in Claude Code (for Cloudflare Workers whitelisting step — optional, non-blocking if unavailable)

---

Usage

Onboard from a Jira ticket

/onboard-api PLT-99452

Fetches the ticket, extracts Swagger URL + endpoints, creates branch, runs full implementation, raises PR.

Onboard from direct input

/onboard-api Swagger: https://alpha.uipath.com/orchestrator_/swagger/v17.0/swagger.json Endpoints: GET /odata/Jobs, GET /odata/Jobs({key})

Add a method to an existing service

/onboard-api Add getById to Jobs service. Swagger: https://alpha.uipath.com/orchestrator_/swagger/v17.0/swagger.json Endpoint: GET /odata/Jobs({key})

Same workflow — onboard-api handles branch, implementation (via sdk-service-dev), and PR.

Non-onboarding work (bug fixes, refactoring, reviews)

/sdk-service-dev fix the transform pipeline in the Entities service
/sdk-service-dev review the pagination setup in Jobs

Use sdk-service-dev directly only when there's no endpoint to onboard.

---

Example Output

PR #290 (feat(orchestrator): add Jobs getAll service) was generated end-to-end from Jira ticket PLT-99452 using these skills. It produced:

• FolderScopedService implementation with OData pagination and field mapping
• Full type definitions, constants, and models
• Unit tests (5 tests) + integration tests
• Build system wiring (package.json exports, rollup.config.js)
• Doc updates (oauth-scopes.md, pagination.md table)
• Structured PR description with field mapping table and usage examples

---

Files Changed

File	Purpose
.claude/skills/onboard-api/SKILL.md	Orchestrator skill — input collection, branch creation, CF Workers whitelisting, PR workflow
.claude/skills/onboard-api/references/cloudflare-whitelist.md	Procedure for adding endpoint patterns to CF Workers proxy whitelist
.claude/skills/sdk-service-dev/SKILL.md	Implementation skill — all conventions, decision trees, verification checklist
.claude/skills/sdk-service-dev/references/onboarding.md	Full onboarding guide — API inspection, response design, service placement, method binding
.claude/skills/sdk-service-dev/references/transforms.md	Response transformation pipeline and standard field renames
.claude/skills/sdk-service-dev/references/pagination.md	Pagination setup — offset vs token, constants, conditional types
.claude/skills/sdk-service-dev/references/testing.md	Unit + integration test conventions
.claude/skills/sdk-service-dev/references/e2e-testing.md	Ephemeral React app E2E validation workflow
.claude/skills/sdk-service-dev/references/jsdoc.md	JSDoc rules, telemetry, required doc updates
CLAUDE.md	Updated to route all SDK service work through the skills
.gitignore	Added .env.skills, .uipath/, .worktrees/

---

🤖 Generated with Claude Code

[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

[ninja-shreyash]

Closing in favour of #302