How do I install the Plain Support skill?

Run npx skillmds@latest add team-plain/plain-support in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Plain Support skill do?

Access to Plain customer support platform. Read customers, threads, timeline, and help center content. Add notes to threads. Create, update, and publish help center articles. It is listed under Coding & Dev Tools on SkillMD.

Is Plain Support safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Plain Support?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Plain Support free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Plain Support?

team-plain (@team-plain) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Plain Support by team-plain — Agent Skill

Name: Plain Support
Author: team-plain

Plain API Skill

Access to the Plain customer support platform via GraphQL API. This skill provides commands to read customers, support threads, timeline entries, help center content, and more. Notes can be added to threads. Help center articles can be created, updated, and published directly.

Prerequisites

PLAIN_API_KEY environment variable set with your API key
curl and jq installed

Quick Reference

Customers (Read Only)

# List customers
scripts/plain-api.sh customer list --first 10

# Get customer by ID
scripts/plain-api.sh customer get c_01ABC...

# Get customer by email
scripts/plain-api.sh customer get-by-email user@example.com

# Get customer by external ID
scripts/plain-api.sh customer get-by-external-id your-system-id

# Search customers
scripts/plain-api.sh customer search "john doe"

Threads (Read + Write)

# List threads (TODO status by default)
scripts/plain-api.sh thread list --first 20

# List all threads including done
scripts/plain-api.sh thread list --status all

# List done threads
scripts/plain-api.sh thread list --status DONE

# List threads by priority
scripts/plain-api.sh thread list --priority urgent
scripts/plain-api.sh thread list --priority high
scripts/plain-api.sh thread list --status TODO --priority low

# Get thread details
scripts/plain-api.sh thread get th_01ABC...

# Search threads
scripts/plain-api.sh thread search "billing issue"

# Get thread timeline (all messages, events, status changes)
scripts/plain-api.sh thread timeline th_01ABC... --first 50

# Paginate through timeline
scripts/plain-api.sh thread timeline th_01ABC... --first 20 --after "cursor_from_previous_page"

# Add a note to a thread (internal note, not visible to customer)
scripts/plain-api.sh thread note th_01ABC... --text "This is an internal note"

# Add a note with markdown formatting
scripts/plain-api.sh thread note th_01ABC... --text "Note text" --markdown "**Bold** and *italic*"

# Add a note from a file (for longer notes)
scripts/plain-api.sh thread note th_01ABC... --text-file /path/to/note.txt

Thread note options:

Option	Required	Description
`--text`	Yes*	Plain text content of the note
`--text-file`	Yes*	Path to file containing note text
`--markdown`	No	Markdown formatted version of the note

*Either --text or --text-file is required.

Thread list options:

Option	Description
`--status`	Filter by status: `TODO`, `SNOOZED`, `DONE`, or `all`
`--priority`	Filter by priority: `urgent`, `high`, `normal`, `low`
`--customer`	Filter by customer ID
`--first`	Number of results (default: 10)

Thread priorities: urgent > high > normal (default) > low

Thread Links (Read + Write)

Attach external issues (GitHub, etc.) to a thread. Plain fetches title, URL, description, and status from the integration server-side — only the ref is needed.

# Add a GitHub issue or PR — accepts URL, shorthand, or canonical sourceId
scripts/plain-api.sh thread link add th_01ABC... https://github.com/owner/repo/issues/45
scripts/plain-api.sh thread link add th_01ABC... https://github.com/owner/repo/pull/45
scripts/plain-api.sh thread link add th_01ABC... owner/repo#45
scripts/plain-api.sh thread link add th_01ABC... owner/repo/45

# List links on a thread
scripts/plain-api.sh thread link list th_01ABC...

Thread link add options:

Option	Required	Description
`<thread_id>`	Yes	Thread to attach the link to
`<ref>`	Yes	GitHub URL, `owner/repo#N`, or `owner/repo/N`
`--source`	No	Source type (default: `github_issue`). Other values: `shortcut_issue`, `rootly_incident`, `incidentio_incident` — for these, pass the integration's native sourceId as `<ref>`

Notes:

The workspace must have the relevant integration configured (e.g., GitHub) for Plain to resolve metadata. If not, the add call returns an error.
Removing links is not supported via API key — delete from the Plain UI.
Plain does not expose searchThreadLinkCandidates to machine users, so the agent must supply the ref directly (parse from a URL the customer pasted, etc.).

Companies (Read Only)

# List companies
scripts/plain-api.sh company list --first 10

# Get company by ID
scripts/plain-api.sh company get co_01ABC...

Tenants (Read Only)

# List tenants
scripts/plain-api.sh tenant list --first 10

# Get tenant by ID
scripts/plain-api.sh tenant get ten_01ABC...

Labels (Read Only)

# List available label types
scripts/plain-api.sh label list --first 20

Help Center (Read + Write)

# List help centers
scripts/plain-api.sh helpcenter list

# Get help center details
scripts/plain-api.sh helpcenter get hc_01ABC...

# List articles in help center
scripts/plain-api.sh helpcenter articles hc_01ABC... --first 20

# Get article by ID
scripts/plain-api.sh helpcenter article get hca_01ABC...

# Get article by slug
scripts/plain-api.sh helpcenter article get-by-slug hc_01ABC... my-article-slug

# Create new article (defaults to DRAFT status)
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --title "How to reset password" \
  --description "Step-by-step guide for resetting your password" \
  --content "<h1>Reset Password</h1><p>Follow these steps...</p>"

# Create and publish article directly
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --title "Getting Started" \
  --description "Quick start guide for new users" \
  --content "<p>Welcome!</p>" \
  --status PUBLISHED

# Update existing article
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --id hca_01ABC... \
  --title "Updated Title" \
  --description "Updated description" \
  --content "<p>New content</p>"

# Use --content-file for large HTML content (recommended)
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --title "Detailed Guide" \
  --description "Comprehensive documentation" \
  --content-file /path/to/article.html \
  --status PUBLISHED

# Get article group
scripts/plain-api.sh helpcenter group get hcag_01ABC...

# Create article group
scripts/plain-api.sh helpcenter group create hc_01ABC... --name "Getting Started"

# Create nested article group
scripts/plain-api.sh helpcenter group create hc_01ABC... --name "Advanced Topics" --parent hcag_01PARENT...

# Update article group
scripts/plain-api.sh helpcenter group update hcag_01ABC... --name "New Group Name"

# Delete article group
scripts/plain-api.sh helpcenter group delete hcag_01ABC...

Article upsert options:

Option	Required	Description
`--title`	Yes	Article title
`--description`	Yes	Short description (shown in article lists)
`--content`	Yes*	HTML content (inline)
`--content-file`	Yes*	Path to file containing HTML content
`--id`	No	Article ID (for updates)
`--group`	No	Article group ID
`--status`	No	DRAFT (default) or PUBLISHED

*Either --content or --content-file is required. Use --content-file for large content.

Note: The response includes a link field with the URL to edit the article in the Plain UI:

{
  "data": { ... },
  "link": "https://app.plain.com/workspace/w_01.../help-center/hc_01.../articles/hca_01.../"
}

Tiers & SLAs (Read Only)

# List tiers with SLA configurations
scripts/plain-api.sh tier list

# Get tier details
scripts/plain-api.sh tier get tier_01ABC...

Workspace

# Get current workspace info
scripts/plain-api.sh workspace

Common Workflows

Research customer history

Get customer: customer get c_... or customer get-by-email user@example.com
List their threads: thread list --customer c_... --status all
Get thread details: thread get th_...
Read full conversation: thread timeline th_... --first 100

Read thread conversation

Get thread: thread get th_...
Fetch timeline entries: thread timeline th_... --first 50
Extract messages: Look for EmailEntry, ChatEntry, SlackMessageEntry, etc. in the response
Paginate if needed: Use --after with cursor from pageInfo.endCursor

Add internal note to thread

Get thread ID from URL or search: thread search "issue keyword"
Add note: thread note th_... --text "Investigation notes here"
Verify in timeline: thread timeline th_... --first 5

Create or update help article

List help centers: helpcenter list
Write HTML content to a file (for large articles): /tmp/article.html

Create/update article:

helpcenter article upsert hc_... \
  --title "Article Title" \
  --description "Short description" \
  --content-file /tmp/article.html \
  --status PUBLISHED

Use the returned link to view/edit in Plain UI

Entity Reference

See references/ENTITIES.md for detailed documentation on all entities including:

Customer fields and statuses
Thread status, priority, and channels
Timeline entry types (24 types: emails, chats, notes, events, status changes, etc.)
Company and Tenant structures
Label and LabelType definitions
Help Center, Article, and ArticleGroup schemas
Tier and SLA configurations

Environment Variables

Variable	Required	Description
`PLAIN_API_KEY`	Yes	Your Plain API key
`PLAIN_API_URL`	No	API endpoint (default: `https://core-api.uk.plain.com/graphql/v1`)

Output Format

All commands return JSON. Use jq for parsing:

# Get just customer name
scripts/plain-api.sh customer get c_01ABC... | jq '.data.customer.fullName'

# Get thread IDs
scripts/plain-api.sh thread list | jq '.data.threads.edges[].node.id'

# Get timeline message content
scripts/plain-api.sh thread timeline th_01ABC... | jq '.data.thread.timelineEntries.edges[].node.entry'

# Get link from article creation
scripts/plain-api.sh helpcenter article upsert hc_... --title "Test" --content "<p>Test</p>" | jq -r '.link'

Plain Support

File contents

Plain API Skill

Prerequisites

Quick Reference

Customers (Read Only)

Threads (Read + Write)

Thread Links (Read + Write)

Companies (Read Only)

Tenants (Read Only)

Labels (Read Only)

Help Center (Read + Write)

Tiers & SLAs (Read Only)

Workspace

Common Workflows

Research customer history

Read thread conversation

Add internal note to thread

Create or update help article

Entity Reference

Environment Variables

Output Format

Frequently asked questions

Plain Support

File contents

Plain API Skill

Prerequisites

Quick Reference

Customers (Read Only)

Threads (Read + Write)

Thread Links (Read + Write)

Companies (Read Only)

Tenants (Read Only)

Labels (Read Only)

Help Center (Read + Write)

Tiers & SLAs (Read Only)

Workspace

Common Workflows

Research customer history

Read thread conversation

Add internal note to thread

Create or update help article

Entity Reference

Environment Variables

Output Format

Related skills

Frequently asked questions

How do I install the Plain Support skill?

What does the Plain Support skill do?

Is Plain Support safe to use?

Which AI agents work with Plain Support?

Is Plain Support free to use?

Who published Plain Support?