The Prompting Company Skill

You can interact with The Prompting Company (TPC) platform on behalf of the user.
TPC is a brand analytics platform that tracks how brands appear across AI search engines
(ChatGPT, Claude, Gemini, Perplexity, Google AI Overview) and helps optimize AI visibility.

Authentication

All API calls use session cookie authentication via Better Auth.

Required environment variables:

- TPC_SESSION_TOKEN — the __Secure-better-auth.session_token cookie value (user provides this)

Configuration (hardcoded):

- TPC_BASE_URL — always use https://app.promptingco.com (production)
INLINECODE4 — fetched dynamically via /api/v1/brands endpoint (see First-Time Setup)
INLINECODE6 — optional, derived from brand selection if needed

Note: In all curl examples below, $TPC_BRAND_ID represents the brand ID selected by the user during first-time setup. Replace it with the actual brand ID value when making requests.

Every curl request must include:
CODEBLOCK0

Response format: All endpoints return JSON wrapped in:

{ "ok": true, "data": { ... } }

or on error:

{ "ok": false, "code": "UNAUTHORIZED", "message": "...", "details": null }

First-Time Setup

On first use, the skill needs to know which brand to work with.

Step 1: Verify session token

CODEBLOCK3

Step 2: Fetch available brands

CODEBLOCK4

The session token automatically scopes to brands the user has access to.

Step 3: Let user select their brand

Use AskUserQuestion to present brand options:

CODEBLOCK5

Step 4: Store selected brand ID

Use the selected brand ID for all subsequent API calls. Do NOT require the user to manually set TPC_BRAND_ID — just store it in memory for the session.

Request Checklist

Before every API request:

1. ✅ Verify TPC_SESSION_TOKEN is provided by user
✅ Use hardcoded base URL: INLINECODE12
✅ If no brand selected yet, run First-Time Setup to fetch and select brand
✅ Include Cookie: __Secure-better-auth.session_token=$TPC_SESSION_TOKEN header in all requests
✅ Always check response ok field before processing data

If session token is missing, ask the user to provide their __Secure-better-auth.session_token cookie value from The Prompting Company platform.

Getting Started

After the skill is installed and the user has selected their brand, present this welcome message:

CODEBLOCK6

User Flow: Track More Prompts

When user selects option 1, present:

CODEBLOCK7

If user chooses A (Track new prompt):

1. Ask user to provide the prompt text they want to track
Fetch user personas for the brand via INLINECODE16
Select the first persona (default) or let user choose if multiple exist
Automatically select answer engines: chatgpt, gemini, deepseek, sonar (Perplexity)
Create the prompt with conversation queries via INLINECODE21
Use maxTurns: 1 as default for all queries
Spawn a subagent to handle the prompt creation workflow

If user chooses B (Get recommendations):

1. Fetch pending prompts via INLINECODE23
Show list of recommended prompts
Let user select which ones to approve
Spawn a subagent to handle the approval workflow

User Flow: Publish More Content

When user selects option 2, present:

CODEBLOCK8

1. Fetch all prompts via /api/v1/prompt-topics and INLINECODE25
Show list of prompts grouped by topic
Let user select which prompt to create content for
Fetch existing documents via INLINECODE26
Create a new draft or update existing document
Spawn a subagent to handle the content creation workflow

User Flow: Get Stats

When user selects option 3, present:

CODEBLOCK9

1. Fetch SOV data via INLINECODE27
Fetch AI traffic via INLINECODE28
Display:

- Current SOV percentage - SOV trend (up/down from last period) - Top AI bots sending traffic (ChatGPT, Claude, Gemini, etc.) - Top pages visited by AI bots

4. Spawn a subagent to fetch and format the stats

Using Subagents

IMPORTANT: For all multi-step workflows, spawn a subagent using the Task tool instead of handling the workflow directly.

When to Spawn Subagents

Workflow	Spawn Subagent?	Reason
Track new prompt	YES	Multi-step: validate, check duplicates, create, verify
Approve recommended prompts

Subagent Invocation Pattern

Example: Track New Prompt

CODEBLOCK10

Example: Get Stats

CODEBLOCK11

Example: Publish Content

CODEBLOCK12

Capabilities Overview

Capability	When to use
Competitor Analysis	User asks about competitor SOV, brand comparisons, engine breakdown
Prompt Management

User wants to add prompts to track, list topics, check duplicates |
| Content Reminders | User asks about pending drafts, approvals, publishing content |
| Stats & Analytics | User wants SOV trends, AI traffic numbers, daily/monthly reports |
| Brand Management | User wants to list brands, search brands, see brand details |

1. Competitor Analysis

Get Share of Voice (SOV) over time

Returns SOV timeseries for a brand (optionally compared against a competitor).

CODEBLOCK13

Parameters:

- brandId (required) — the brand to get SOV for
INLINECODE30 (optional) — competitor brand ID to compare against; defaults to INLINECODE31
INLINECODE32 (optional) — filter by a specific view
INLINECODE33 (optional) — 7d, 30d, or 90d (default 30d)

Response data shape:
CODEBLOCK14

Get SOV breakdown by AI engine

Shows how a brand performs on each AI engine (ChatGPT, Claude, Gemini, etc.).

CODEBLOCK15

Parameters: Same as presence-rate.

Response data shape:
CODEBLOCK16

Get competitor brands

CODEBLOCK17

Get pinned competitors

CODEBLOCK18

2. Prompt Management

List prompt topics

Topics group related prompts together for organized tracking.

CODEBLOCK19

Parameters:

- brandId (required)
INLINECODE39 (optional, default 1)
INLINECODE40 (optional, default 10)
INLINECODE41 (optional) — text search across topic titles

Response data shape:
CODEBLOCK20

Get prompts in a topic

CODEBLOCK21

Get SOV for a topic

Returns aggregated SOV across all prompts in a topic.

CODEBLOCK22

Get industry rankings for a topic

CODEBLOCK23

List user personas

Retrieves user personas for a brand (required for creating prompts).

CODEBLOCK24

Response data shape:
CODEBLOCK25

Create a custom prompt for tracking

Creates a custom prompt with conversation queries across multiple AI engines.

CODEBLOCK26

Parameters:

- brandId (required) — the brand ID
INLINECODE43 (required) — array of conversation queries to create

- prompt (required) — the prompt text to track
- model (required) — one of: chatgpt, gemini, deepseek, sonar
- maxTurns (required) — number of conversation turns (default: 1)
- userPersonaId (required) — persona ID from /api/v1/personas
- userPersona (required) — persona name for display

Response data shape:
CODEBLOCK27

Generate AI-suggested prompt

Generates an AI-suggested prompt based on brand and persona (not for direct tracking).

CODEBLOCK28

Note: This endpoint returns plain text (the generated prompt question), not JSON. Use this for inspiration, not for tracking. To track a prompt, use /api/v1/conversation-queries/bulk.

Bulk generate prompts

CODEBLOCK29

Check bulk job status:
CODEBLOCK30

Check for duplicate prompts

CODEBLOCK31

Submit prompt for review

CODEBLOCK32

List pending prompts

CODEBLOCK33

List archived prompts

CODEBLOCK34

Restore an archived prompt

CODEBLOCK35

3. Content & Draft Management

List documents

CODEBLOCK36

Parameters:

- brandId (required)
INLINECODE56, pageSize (optional, max 100)
INLINECODE58 (optional) — search query
INLINECODE59 (optional) — true or INLINECODE61
INLINECODE62 (optional) — e.g. updatedAt:desc, INLINECODE64
INLINECODE65 (optional) — true for paginated response

Paginated response shape:
CODEBLOCK37

Publish a draft

Queues a draft for publishing to the live site.

CODEBLOCK38

Response:
CODEBLOCK39

Submit a draft for review

CODEBLOCK40

List reviewed drafts

CODEBLOCK41

Batch publish drafts

CODEBLOCK42

Check batch status:
CODEBLOCK43

Create a new document

CODEBLOCK44

Create a draft for a document

CODEBLOCK45

4. Stats & Analytics

Get AI traffic stats

Shows how much traffic AI bots are sending to the brand's website.

CODEBLOCK46

Parameters:

- brandId (required)
INLINECODE68 (optional) — format INLINECODE69
INLINECODE70 (optional) — format INLINECODE71
INLINECODE72 (optional) — comma-separated list of providers

Response data shape:
CODEBLOCK47

Get human traffic stats (baseline comparison)

CODEBLOCK48

Get SOV daily trend (last 30 days)

Use the presence-rate endpoint with timeframe=30d:
CODEBLOCK49

Get SOV monthly overview

Use timeframe=90d for a broader monthly view:
CODEBLOCK50

Get prompt-level SOV

CODEBLOCK51

Get brand mentions for a prompt

CODEBLOCK52

Get competitor mentions for a prompt

CODEBLOCK53

5. Brand Management

List all brands

CODEBLOCK54

Parameters:

- search (optional)
INLINECODE76, pageSize (optional)
INLINECODE78 — createdAt or INLINECODE80
INLINECODE81 — asc or INLINECODE83
INLINECODE84 — true to get all brands
INLINECODE86 — true to include domain info

Response data shape:
CODEBLOCK55

Search brands

CODEBLOCK56

6. Weekly Reports

Preview weekly report

CODEBLOCK57

Common Workflows

IMPORTANT: All workflows below should be handled by spawning a subagent using the Task tool.

Workflow 1: Track More Prompts

Trigger: User selects "Track more prompts" from the getting started menu.

Subagent Task:

CODEBLOCK58

Workflow 2: Publish More Content

Trigger: User selects "Publish more content" from the getting started menu.

Subagent Task:

CODEBLOCK59

Workflow 3: Get Stats

Trigger: User selects "Get stats" from the getting started menu.

Subagent Task:

CODEBLOCK60

Daily Stats Briefing

Trigger: User asks for "daily update" or "daily stats".

Spawn subagent with:

- Fetch SOV trend: INLINECODE88
Fetch AI traffic: INLINECODE89
Fetch per-engine breakdown: INLINECODE90
Summarize: latest SOV %, change from last week, top AI engines, total AI visits

Competitor Comparison

Trigger: User asks to compare against a competitor.

Spawn subagent with:

1. Get pinned competitors: INLINECODE91
Get own SOV: INLINECODE92
Get competitor SOV: INLINECODE93
Get per-engine breakdown for both
Present side-by-side comparison with trends

Error Handling

Response Structure

Every API response follows this format:

Success:
CODEBLOCK61

Error:
CODEBLOCK62

Always check response.ok before processing data.

Error Codes

Code	HTTP Status	Description	Action
INLINECODE95	401	Session token is expired or invalid	Ask user to provide a new session token from their browser
INLINECODE96

Pre-Request Validation

Before making any API call:

1. Verify session token exists:

CODEBLOCK63

2. Validate UUID parameters:

- brandId, promptId, documentId, topicId must be valid UUIDs - Format: INLINECODE106

3. Validate date parameters:

- Must be ISO 8601 format: YYYY-MM-DD - startDate must be before endDate - Example: INLINECODE110

4. Validate enum parameters:

- timeframe: only 7d, 30d, or 90d - sortBy: only valid column names - sortOrder: only asc or desc - action: only approve or INLINECODE121

5. Validate pagination:

- page must be >= 1 - pageSize must be <= 100

Error Recovery Flows

401 Unauthorized (Session Expired)

CODEBLOCK64

429 Rate Limited

CODEBLOCK65

404 Not Found

CODEBLOCK66

500 Internal Server Error

CODEBLOCK67

Parameter Validation Examples

Date Range:
CODEBLOCK68

UUID:
CODEBLOCK69

Error Reporting to User

When reporting errors, always include:

1. What went wrong: Clear error message
Why it happened: The error code and server message
What to do next: Actionable steps to fix

Example:

❌ Error: Unable to fetch brand data

Reason: UNAUTHORIZED - Session token has expired

Action needed:
1. Go to https://app.promptingco.com
2. Open DevTools (F12) → Application → Cookies
3. Copy the "__Secure-better-auth.session_token" value
4. Update your TPC_SESSION_TOKEN and try again

Tips

- Brand Selection: Always use the user's selected brand as the default unless they specify another brand by name.
SOV Display: When showing SOV values, multiply value by 100 to display as percentage (e.g. 0.42 = 42%).
Date Format: Always use ISO 8601 format for dates: YYYY-MM-DD.
Per-Engine SOV: The sov field in per-engine responses is already a 0-100 percentage (no conversion needed).
Timeframe Options:

- 7d — weekly view - 30d — monthly view (default) - 90d — quarterly view

- Daily Stats: When user asks for "daily stats", use timeframe=7d and show the latest data point plus trend.
Monthly Stats: When user asks for "monthly stats", use timeframe=30d.
Response Parsing: Always check response.ok === true before accessing response.data.
Error Messages: When errors occur, show the message field from the API response to the user.
Brand Context: If the user mentions a brand name, search for it via /api/v1/brands/search to get the brand ID.

The Prompting Company 技能

你可以代表用户与 The Prompting Company（TPC）平台进行交互。
TPC 是一个品牌分析平台，用于追踪品牌在 AI 搜索引擎（ChatGPT、Claude、Gemini、Perplexity、Google AI Overview）中的出现情况，并帮助优化 AI 可见性。

身份验证

所有 API 调用均通过 Better Auth 使用会话 Cookie 进行身份验证。

所需环境变量：

- TPCSESSIONTOKEN — Secure-better-auth.session_token Cookie 值（由用户提供）

配置（硬编码）：

- TPCBASEURL — 始终使用 https://app.promptingco.com（生产环境）
TPCBRANDID — 通过 /api/v1/brands 端点动态获取（参见首次设置）
TPCORGSLUG — 可选，根据需要从品牌选择中派生

注意： 在以下所有 curl 示例中，$TPCBRANDID 代表用户在首次设置期间选择的品牌 ID。发起请求时，请将其替换为实际的品牌 ID 值。

每个 curl 请求必须包含：

-H Cookie: Secure-better-auth.sessiontoken=$TPCSESSION_TOKEN

响应格式： 所有端点返回 JSON，格式为：
json
{ ok: true, data: { ... } }

或错误时：
json
{ ok: false, code: UNAUTHORIZED, message: ..., details: null }

首次设置

首次使用时，技能需要知道要操作哪个品牌。

步骤 1：验证会话令牌

bash

用户只需提供此值

TPCSESSIONTOKEN=用户的会话令牌

步骤 2：获取可用品牌

bash curl -s https://app.promptingco.com/api/v1/brands?fetchAll=true \ -H Cookie: Secure-better-auth.sessiontoken=$TPCSESSION_TOKEN

会话令牌会自动限定范围到用户有权访问的品牌。

步骤 3：让用户选择品牌

使用 AskUserQuestion 呈现品牌选项：

typescript
// 解析 /api/v1/brands 的响应
const brands = response.data.brands;

// 呈现给用户
{
question: 您想操作哪个品牌？,
header: 品牌,
options: brands.map(b => ({
label: b.name,
description: ${b.slug} • ${b.organizationId}
})),
multiSelect: false
}

步骤 4：存储所选品牌 ID

使用所选品牌 ID 进行所有后续 API 调用。不要要求用户手动设置 TPCBRANDID — 只需在会话期间将其存储在内存中。

请求检查清单

每次 API 请求前：

1. ✅ 验证用户已提供 TPCSESSIONTOKEN
✅ 使用硬编码的基础 URL：https://app.promptingco.com
✅ 如果尚未选择品牌，运行首次设置以获取并选择品牌
✅ 在所有请求中包含 Cookie: Secure-better-auth.sessiontoken=$TPCSESSION_TOKEN 标头
✅ 在处理数据前始终检查响应中的 ok 字段

如果缺少会话令牌，请要求用户从 The Prompting Company 平台提供其 Secure-better-auth.session_token Cookie 值。

入门指南

技能安装完成且用户选择品牌后，呈现以下欢迎消息：

技能安装成功。

您的后续步骤：

1. 追踪更多提示词
发布更多内容
查看统计数据

您想做什么？

用户流程：追踪更多提示词

当用户选择选项 1 时，呈现：

您希望如何追踪提示词？

A. 自行追踪新提示词
B. 从现有提示词获取推荐

选择一个选项：

如果用户选择 A（追踪新提示词）：

1. 要求用户提供要追踪的提示词文本
通过 /api/v1/personas?brandId=... 获取品牌的用户画像
选择第一个画像（默认）或如果存在多个则让用户选择
自动选择回答引擎：chatgpt、gemini、deepseek、sonar（Perplexity）
通过 /api/v1/conversation-queries/bulk 创建带有对话查询的提示词
对所有查询使用 maxTurns: 1 作为默认值
生成子代理来处理提示词创建工作流

如果用户选择 B（获取推荐）：

1. 通过 /api/v1/prompts/pending 获取待处理提示词
显示推荐提示词列表
让用户选择要批准的提示词
生成子代理来处理批准工作流

用户流程：发布更多内容

当用户选择选项 2 时，呈现：

让我们从您追踪的提示词创建内容。

步骤 1：获取您的提示词...

1. 通过 /api/v1/prompt-topics 和 /api/v1/prompt-topics/{topicId}/prompts 获取所有提示词
显示按主题分组的提示词列表
让用户选择要为其创建内容的提示词
通过 /api/v1/agentic-documents 获取现有文档
创建新草稿或更新现有文档
生成子代理来处理内容创建工作流

用户流程：查看统计数据

当用户选择选项 3 时，呈现：

正在获取您的统计数据...

声量份额 (SOV)
────────────────────
[SOV 数据在此]

AI 流量统计
────────────────────
热门机器人：
[机器人流量数据]

热门页面：
[页面流量数据]

1. 通过 /api/v1/presence-rate?brandId=...&timeframe=30d 获取 SOV 数据
通过 /api/v1/ai-traffic-stats?brandId=... 获取 AI 流量
显示：

- 当前 SOV 百分比 - SOV 趋势（与上一期相比上升/下降） - 发送流量的热门 AI 机器人（ChatGPT、Claude、Gemini 等） - AI 机器人访问的热门页面

4. 生成子代理来获取并格式化统计数据

使用子代理

重要提示： 对于所有多步骤工作流，请使用 Task 工具生成子代理，而不是直接处理工作流。

何时生成子代理

工作流	生成子代理？	原因
追踪新提示词	是	多步骤：验证、检查重复、创建、验证
批准推荐提示词

子代理调用模式

示例：追踪新提示词

typescript
// 当用户想要追踪新提示词时：
Task({
subagent_type: general-purpose,
description: 追踪新提示词工作流,
prompt:
帮助用户在 The Prompting Company 平台上追踪新提示词。

上下文：
- 品牌 ID：${brandId}
- 会话令牌：${TPCSESSIONTOKEN}
- 基础 URL：https://app.promptingco.com

步骤：
1. 询问用户要追踪的提示词文本
2. 检查重复项：GET /api/v1/prompts/check-duplicates?brandId=${brandId}&message=<提示词文本>
3. 如果存在重复项，询问用户是否要继续
4. 获取用户画像：GET /api/v1/personas?brandId=${brandId}
5. 使用第一个画像作为默认（如果多个则让用户选择）
6. 创建带有 4 个对话查询（每个引擎一个）的提示词：
POST /api/v1/conversation-queries/bulk
请求体：{
brandId: ${brandId},
queries: [
{ prompt: <用户文本>, model: chatgpt, maxTurns: 1, userPersonaId: <画像ID>, userPersona: <画像名称> },
{ prompt: <用户文本>, model: gemini, maxTurns: 1, userPersonaId: <画像ID>, userPerson

prompting-co提示协作

prompting-co

The Prompting Company Skill

Authentication

First-Time Setup

Step 1: Verify session token

Step 2: Fetch available brands

Step 3: Let user select their brand

Step 4: Store selected brand ID

Request Checklist

Getting Started

User Flow: Track More Prompts

User Flow: Publish More Content

User Flow: Get Stats

Using Subagents

When to Spawn Subagents

Subagent Invocation Pattern

Capabilities Overview

1. Competitor Analysis

Get Share of Voice (SOV) over time

Get SOV breakdown by AI engine

Get competitor brands

Get pinned competitors

2. Prompt Management

List prompt topics

Get prompts in a topic

Get SOV for a topic

Get industry rankings for a topic

List user personas

Create a custom prompt for tracking

Generate AI-suggested prompt

Bulk generate prompts

Check for duplicate prompts

Submit prompt for review

List pending prompts

List archived prompts

Restore an archived prompt

3. Content & Draft Management

List documents

Publish a draft

Submit a draft for review

List reviewed drafts

Batch publish drafts

Create a new document

Create a draft for a document

4. Stats & Analytics

Get AI traffic stats

Get human traffic stats (baseline comparison)

Get SOV daily trend (last 30 days)

Get SOV monthly overview

Get prompt-level SOV

Get brand mentions for a prompt

Get competitor mentions for a prompt

5. Brand Management

List all brands

Search brands

6. Weekly Reports

Preview weekly report

Common Workflows

Workflow 1: Track More Prompts

Workflow 2: Publish More Content

Workflow 3: Get Stats

Daily Stats Briefing

Competitor Comparison

Error Handling

Response Structure

Error Codes

Pre-Request Validation

Error Recovery Flows

401 Unauthorized (Session Expired)

429 Rate Limited

404 Not Found

500 Internal Server Error

Parameter Validation Examples

Error Reporting to User

Tips

The Prompting Company 技能

身份验证

首次设置

步骤 1：验证会话令牌