platform-agentsetup-categories-fetch

SKILL.md

platform-agentsetup-categories-fetch

Fetch prompt categories from the Agentic Setup Categories Connect API on a connected Salesforce org.

Scope

In scope:

Calling GET /services/data/{apiVersion}/agenticsetup/categories via SF CLI

Passing the fetchPrompts query parameter to include nested prompts

Parsing and presenting the JSON response (categories, labels, prompts)

Handling errors (403 when feature is disabled, auth failures)

Out of scope — delegate elsewhere:

Creating or modifying prompt categories → not supported via this API (read-only)

Org authentication setup → use sf org login separately

Permission set assignment → assigning-permission-set

Required Inputs

The agent needs:

A connected org (already authenticated via sf org login)

Optionally: whether to include nested prompts (fetchPrompts=true)

Optionally: target API version (default: v67.0). Replace v67.0 in the URL with the user-specified version if provided.

Workflow

1. Verify org connectivity

sf org display --json

Confirm the org is authenticated and extract the instance URL. If no default org is set, ask the user which org to target with --target-org.

2. Call the Categories API

Basic call (categories only):

sf api request rest /services/data/v67.0/agenticsetup/categories --method GET

With nested prompts:

sf api request rest "/services/data/v67.0/agenticsetup/categories?fetchPrompts=true" --method GET

3. Parse and present the response

The API returns a JSON object with a categories array. Each category has name, label, and prompts fields. See references/api-response-schema.md for the full response structure and examples for both fetchPrompts=true and fetchPrompts=false.

Present the results clearly:

List categories with their name and label

If fetchPrompts=true was used, show nested prompts under each category

Note any categories with empty prompts arrays (means no prompts exist for that category)

4. Handle errors

Error
Meaning
Action

Success (exit 0)
200 OK
Parse and display results

FUNCTIONALITY_NOT_ENABLED
Feature not enabled for this org/user
Tell user the Agentic Setup Categories feature needs to be enabled — check Setup > Einstein/Agentforce

INVALID_SESSION_ID
Session expired
Re-authenticate with sf org login

NOT_FOUND
Endpoint not found
API version too old or feature not deployed to this org

Rules / Constraints

Rule
Rationale

Always use sf api request rest — never curl or raw HTTP
curl bypasses ~/.sfdx session tokens and requires manual Authorization headers, making it brittle

NEVER use SOQL queries
Categories are NOT in standard objects — only available via this Connect REST API

NEVER generate files (LWC, Apex, XML)
This is a data-fetching task, not a code generation task

Default to v67.0 unless user specifies
This is the min-version where the endpoint was introduced

Don't pass fetchPrompts unless asked
Reduces payload size; prompts can be large

Categories are sorted by label
The API returns them alphabetically — don't re-sort

Prompts are sorted by text
Within each category, prompts come alphabetically

Output Expectations

When finishing, present:

Number of categories returned

Category list — name and label for each

Prompts (if requested) — nested under their category

Any errors encountered with suggested fixes

Reference File Index

File
When to read

references/api-response-schema.md
When you need to understand the full response structure and field descriptions