TON-XXXX: Add Skill Catalog pup commands for the agentic onboarding API by tedkahwaji · Pull Request #640 · DataDog/pup

tedkahwaji · 2026-07-13T18:58:04Z

Summary

Adds a pup skills remote command group to the pup CLI that wraps the public routes of Datadog's agentic skills API (agentic-onboarding-api, in dd-source).

Background — what is this for?

Datadog serves a catalog of agent skills: markdown documents that give an AI coding assistant step-by-step instructions for setting something up (e.g. wiring up the AWS integration). The backend also records sessions — a log of which skills an assistant used during a run and how it turned out.

Today an assistant has to make raw HTTP calls (with the JSON:API envelope, auth headers, etc.) to reach those routes. This PR gives it ergonomic pup subcommands instead, so the assistant can just shell out to pup skills remote ….

Note on naming: these commands live under the existing pup skills group but are grouped under a remote subcommand to distinguish them from the other skills subcommands. pup skills list/install/path install the statically bundled skill files onto a local assistant (Claude, Cursor, Codex…); pup skills remote … talks to the remote Datadog catalog over the API. The underlying API paths are still /api/v2/onboarding/* (that's where these routes live), even though the skills served are no longer onboarding-specific.

Commands

All hit the existing /api/v2/onboarding/* routes:

Command	Route
`pup skills remote list [--tag <tag>…] [--org-id N]`	`GET /api/v2/onboarding/skills`
`pup skills remote get <skill_id> [--intent explore\|install\|reference] [--session-id …] [--org-id N]`	`GET /api/v2/onboarding/skills/{skill_id}?format=md`
`pup skills remote sessions create --session-id … --skill-id … --summary … --status …`	`POST /api/v2/onboarding/sessions`

list returns the available skills (id, name, description, cloud provider, required tools, example prompts…). --tag filters the results client-side; repeat it to require multiple tags.
get returns a single skill's instructions. It always requests the markdown representation (format=md) — the raw skill file (YAML frontmatter + body), which is exactly what an assistant consumes to follow the skill — and prints it to stdout. The representation isn't exposed as a flag because there's no reason for the caller to want the JSON:API envelope instead. --session-id correlates the fetch with a recorded session; it is sent as the API's onboarding_run_id query param (only the CLI flag is renamed).
sessions create records the outcome of a run. --status is one of in_progress | completed | failed | abandoned; --skill-id may be repeated. A terminal status (completed/failed/abandoned) requires at least one --skill-id; in_progress may have none. Both rules mirror the server-side validation. There is no --org-id here — the org is derived from the caller's credentials.

Design notes

Opportunistic auth. The list and get routes are OpenAuth (they work without credentials, e.g. before a customer has authenticated). The client attaches an OAuth bearer or API+App key when present so the request is attributed to the caller's org, but never requires them — unlike the shared client::apply_auth, which fails without credentials. sessions create requires authentication.
skill_id is percent-encoded (util_ext::percent_encode) before being interpolated into the /skills/{id} path, so an id containing reserved characters (/, ?) can't rewrite the route or start a query string.
Input validation is client-side (intent, status, terminal-status-requires-skill) so obvious mistakes fail fast with a clear message instead of a 400 round-trip.

Testing

cargo build, cargo clippy --all-targets -- -D warnings, cargo fmt --check — all clean.
cargo test (skills_remote suite) — passes, covering: happy paths, org_id query forwarding, --tag filtering, format=md always sent, --session-id → onboarding_run_id mapping, percent-encoding of reserved-character skill ids, and negative cases (invalid intent, invalid status, 404 surfacing, terminal-status skill-id requirement, in_progress empty-skill-ids allowance).
CLI plumbing confirmed via --help on each subcommand.

🤖 Generated with Claude Code

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0e4ac4bb84

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6784b62eab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Mirrors the query params added in DataDog#640's onboarding skills_get, so `pup skills catalog get` can scope a fetch to an onboarding session/org and record fetch intent. - src/commands/skills.rs: catalog_get takes optional intent (validated against explore/install/reference), session_id, org_id and forwards them as query params. - src/main.rs: SkillsCatalogActions::Get gains --intent, --session-id, --org-id flags. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

tedkahwaji · 2026-07-21T15:15:05Z

@codex review

chatgpt-codex-connector · 2026-07-21T15:23:16Z

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: cce253a1fd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

… API Adds a `remote` subgroup under `pup skills` that wraps the public agentic onboarding API, so an AI assistant can discover hosted skills, fetch their instructions, and record sessions by running `pup` instead of raw HTTP calls. Distinct from the other `skills` subcommands, which install the statically bundled skills onto a local assistant. Commands (all hit /api/v2/onboarding/*): - `pup skills remote list [--tag …] [--org-id N]` GET /api/v2/onboarding/skills. `--tag` filters in memory against each skill's frontmatter tags (repeatable; AND semantics). - `pup skills remote get <skill_id> [--intent …] [--session-id …] [--org-id N]` GET /api/v2/onboarding/skills/{id}?format=md, printed as raw markdown. `--session-id` maps to the API's `onboarding_run_id` query param. - `pup skills remote sessions create --session-id … --skill-id … --summary … --status …` → POST /api/v2/onboarding/sessions (JSON:API). Details: - list/get are public (OpenAuth); sessions create requires authentication and derives the org from the caller (no org_id in the request). - skill_id is percent-encoded before path interpolation. - Terminal session statuses (completed/failed/abandoned) require at least one --skill-id; in_progress may be empty, mirroring the backend. - Read-only guard: `skills` stays exempt for local installs, but `skills remote` is not, so `pup --read-only skills remote sessions create` is correctly blocked (via a new is_read_only_exempt helper). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread src/main.rs Outdated

chatgpt-codex-connector Bot reviewed Jul 13, 2026

View reviewed changes

Comment thread src/commands/onboarding.rs Outdated

rachelyangdog mentioned this pull request Jul 20, 2026

feat(skills): add catalog and session commands backed by Datadog API #614

Closed

5 tasks

tedkahwaji marked this pull request as ready for review July 20, 2026 20:00

tedkahwaji requested a review from a team as a code owner July 20, 2026 20:00

tedkahwaji force-pushed the feat/onboarding-api-commands branch from 6784b62 to e45df6a Compare July 20, 2026 20:15

tedkahwaji changed the title ~~feat(onboarding): add pup commands for the agentic onboarding API~~ feat(catalog): add pup commands for the Datadog agentic skills API Jul 20, 2026

This comment has been minimized.

Sign in to view

tedkahwaji changed the title ~~feat(catalog): add pup commands for the Datadog agentic skills API~~ TON-XXXX: Add Skill Catalog pup commands for the agentic onboarding API Jul 20, 2026

tedkahwaji force-pushed the feat/onboarding-api-commands branch 2 times, most recently from 9566d40 to cce253a Compare July 21, 2026 15:13

tedkahwaji force-pushed the feat/onboarding-api-commands branch 2 times, most recently from 2b2ff83 to f1c332b Compare July 21, 2026 17:19

tedkahwaji force-pushed the feat/onboarding-api-commands branch from f1c332b to acdb192 Compare July 21, 2026 19:45

platinummonkey approved these changes Jul 22, 2026

View reviewed changes

platinummonkey merged commit 1eec9fb into DataDog:main Jul 22, 2026
6 checks passed

BrewTestBot mentioned this pull request Jul 22, 2026

pup 1.7.0 Homebrew/homebrew-core#294663

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

TON-XXXX: Add Skill Catalog pup commands for the agentic onboarding API#640

TON-XXXX: Add Skill Catalog pup commands for the agentic onboarding API#640
platinummonkey merged 1 commit into
DataDog:mainfrom
tedkahwaji:feat/onboarding-api-commands

tedkahwaji commented Jul 13, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

Uh oh!

This comment has been minimized.

tedkahwaji commented Jul 21, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jul 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

tedkahwaji commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Background — what is this for?

Commands

Design notes

Testing

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

This comment has been minimized.

tedkahwaji commented Jul 21, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jul 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tedkahwaji commented Jul 13, 2026 •

edited

Loading