Skip to content

Commit f7b3809

Browse files
dedenededene
committed
feat: add AI agent skill for frontcli
Add SKILL.md so AI coding agents can use frontcli autonomously. Covers all commands, workflows, ID prefixes, and bulk operations. Compatible with Claude Code, Cursor, GitHub Copilot via npx skills.
1 parent 7c35747 commit f7b3809

2 files changed

Lines changed: 251 additions & 0 deletions

File tree

‎.claude/skills/frontcli/SKILL.md‎

Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
---
2+
name: frontcli
3+
description: Interact with Front customer support platform via the frontcli CLI. Use when managing conversations, messages, contacts, tags, drafts, comments, templates, inboxes, teammates, or channels in Front. Triggered by mentions of Front, frontcli, support tickets, customer conversations, or helpdesk operations.
4+
---
5+
6+
# frontcli -- Front CLI
7+
8+
CLI for [Front](https://frontapp.com) customer support. Manages conversations, messages, contacts, tags, drafts, comments, templates, and more.
9+
10+
## Quick Start
11+
12+
Verify auth before any operation:
13+
14+
```bash
15+
frontcli auth status
16+
frontcli whoami --json
17+
```
18+
19+
If not authenticated, the user must run `frontcli auth login` interactively (requires browser for OAuth). Do not attempt auth setup on behalf of the user.
20+
21+
## Core Rules
22+
23+
1. **Always use `--json`** when parsing output. Human-readable format is for display only.
24+
2. **Use correct ID prefixes** -- see ID Reference below. Wrong prefix produces a clear error.
25+
3. **Read before write** -- fetch current state before modifying (archive, assign, tag, reply).
26+
4. **Pipe with jq** -- extract IDs/fields: `frontcli conv list --json | jq -r '._results[].id'`
27+
5. **Multi-account** -- use `--account user@email.com` if the user has multiple Front accounts.
28+
29+
## ID Reference
30+
31+
| Prefix | Resource | Example |
32+
|--------|-------------|--------------|
33+
| `cnv_` | conversation | `cnv_abc123` |
34+
| `msg_` | message | `msg_abc123` |
35+
| `cmt_` | comment | `cmt_abc123` |
36+
| `tea_` | teammate | `tea_abc123` |
37+
| `tag_` | tag | `tag_abc123` |
38+
| `inb_` | inbox | `inb_abc123` |
39+
| `chn_` | channel | `chn_abc123` |
40+
| `ctc_` | contact | `ctc_abc123` |
41+
| `drf_` | draft | `drf_abc123` |
42+
| `rsp_` | template | `rsp_abc123` |
43+
| `att_` | attachment | `att_abc123` |
44+
| `hdl_` | handle | `hdl_abc123` |
45+
46+
## Output Formats
47+
48+
| Flag | Format | Use case |
49+
|------------|--------|----------|
50+
| (default) | Table | User-facing display |
51+
| `--json` | JSON | Agent parsing, scripting |
52+
| `--plain` | TSV | Pipe to awk/cut |
53+
54+
JSON list responses wrap results in `._results[]`. Single-object responses return the object directly.
55+
56+
## Workflows
57+
58+
### Read a Conversation Thread
59+
60+
```bash
61+
# Full message bodies + comments (timeline view)
62+
frontcli conv get cnv_xxx --full --json
63+
64+
# Metadata only
65+
frontcli conv get cnv_xxx --json
66+
67+
# Messages only
68+
frontcli conv messages cnv_xxx --json
69+
70+
# Comments only
71+
frontcli conv comments cnv_xxx --json
72+
```
73+
74+
Use `--full` when you need message content; omit for metadata only.
75+
76+
### Search / List Conversations
77+
78+
```bash
79+
# List recent open conversations
80+
frontcli conv list --status open --limit 10 --json
81+
82+
# List by inbox or tag
83+
frontcli conv list --inbox inb_xxx --json
84+
frontcli conv list --tag tag_xxx --json
85+
86+
# Free-text search
87+
frontcli conv search "customer issue" --json
88+
89+
# Filtered search
90+
frontcli conv search --from client@co.com --status open --json
91+
frontcli conv search --tag tag_xxx --assignee me --json
92+
frontcli conv search --after "2025-01-01" --before "2025-02-01" --json
93+
```
94+
95+
Search flags: `--from`, `--to`, `--recipient`, `--inbox`, `--tag` (repeatable), `--status`, `--assignee`, `--unassigned`, `--before`, `--after`, `--limit`.
96+
97+
### Reply to a Conversation
98+
99+
```bash
100+
frontcli msg reply cnv_xxx --body "Thanks for reaching out."
101+
frontcli msg reply cnv_xxx --body-file ./reply.txt
102+
```
103+
104+
### Send a New Message
105+
106+
Requires a channel ID. Find channels first:
107+
108+
```bash
109+
frontcli channels list --json
110+
frontcli msg send --channel chn_xxx --to user@example.com --subject "Hello" --body "Message body"
111+
```
112+
113+
### Add Internal Comment
114+
115+
Comments are internal notes visible only to teammates:
116+
117+
```bash
118+
frontcli comments create cnv_xxx --body "Internal note: customer is VIP"
119+
```
120+
121+
### Manage Tags
122+
123+
```bash
124+
# List available tags
125+
frontcli tags list --json
126+
127+
# Find tag ID by name
128+
frontcli tags list --json | jq -r '._results[] | select(.name == "Urgent") | .id'
129+
130+
# Tag / untag a conversation
131+
frontcli conv tag cnv_xxx tag_xxx
132+
frontcli conv untag cnv_xxx tag_xxx
133+
```
134+
135+
### Assign / Unassign
136+
137+
```bash
138+
# Find teammate IDs
139+
frontcli teammates list --json
140+
141+
# Assign / unassign
142+
frontcli conv assign cnv_xxx --to tea_xxx
143+
frontcli conv unassign cnv_xxx
144+
```
145+
146+
### Manage Conversation Status
147+
148+
```bash
149+
frontcli conv archive cnv_xxx
150+
frontcli conv open cnv_xxx
151+
frontcli conv trash cnv_xxx
152+
153+
# Snooze (timestamp or duration)
154+
frontcli conv snooze cnv_xxx --until "2025-01-15T09:00:00Z"
155+
frontcli conv snooze cnv_xxx --duration 2h
156+
frontcli conv unsnooze cnv_xxx
157+
```
158+
159+
### Look Up Contacts
160+
161+
```bash
162+
frontcli contacts search "john" --json
163+
frontcli contacts get ctc_xxx --json
164+
frontcli contacts handles ctc_xxx --json
165+
frontcli contacts convos ctc_xxx --json
166+
```
167+
168+
### Templates
169+
170+
```bash
171+
frontcli templates list --json
172+
frontcli templates use rsp_xxx
173+
174+
# Use template body in a reply
175+
BODY=$(frontcli templates use rsp_xxx)
176+
frontcli msg reply cnv_xxx --body "$BODY"
177+
```
178+
179+
### Drafts
180+
181+
```bash
182+
frontcli drafts create cnv_xxx --body "Draft reply"
183+
frontcli drafts list cnv_xxx --json
184+
frontcli drafts update drf_xxx --body "Updated" --draft-version 1
185+
frontcli drafts delete drf_xxx
186+
```
187+
188+
### Custom Fields
189+
190+
```bash
191+
frontcli conv update cnv_xxx --field "Priority=High" --field "Category=Support"
192+
```
193+
194+
## Bulk Operations
195+
196+
```bash
197+
# Archive all conversations with a tag (xargs)
198+
frontcli conv list --tag tag_xxx --json | jq -r '._results[].id' | xargs frontcli conv archive
199+
200+
# Archive from stdin
201+
frontcli conv list --tag tag_xxx --json | jq -r '._results[].id' | frontcli conv archive --ids-from -
202+
203+
# Tag all open unassigned conversations
204+
frontcli conv search --status open --unassigned --json | jq -r '._results[].id' | \
205+
while read id; do frontcli conv tag "$id" tag_xxx; done
206+
```
207+
208+
## Environment Variables
209+
210+
| Variable | Description |
211+
|----------|-------------|
212+
| `FRONT_ACCOUNT` | Default account (avoids `--account`) |
213+
| `FRONT_JSON` | Set `1` for JSON output by default |
214+
| `FRONT_PLAIN` | Set `1` for TSV output by default |
215+
216+
## Command Reference
217+
218+
| Command | Subcommands |
219+
|---------|-------------|
220+
| `conv` | `list`, `get`, `search`, `messages`, `comments`, `archive`, `open`, `trash`, `assign`, `unassign`, `snooze`, `unsnooze`, `followers`, `follow`, `unfollow`, `tag`, `untag`, `update` |
221+
| `msg` | `get`, `send`, `reply`, `attachments`, `attachment download` |
222+
| `drafts` | `create`, `list`, `get`, `update`, `delete` |
223+
| `tags` | `list`, `get`, `create`, `update`, `delete`, `children`, `convos` |
224+
| `contacts` | `list`, `search`, `get`, `handles`, `handle add/delete`, `notes`, `note add`, `convos`, `create`, `update`, `delete`, `merge` |
225+
| `inboxes` | `list`, `get`, `convos`, `channels` |
226+
| `teammates` | `list`, `get`, `convos` |
227+
| `channels` | `list`, `get` |
228+
| `comments` | `list`, `get`, `create` |
229+
| `templates` | `list`, `get`, `use` |
230+
| `whoami` | (show authenticated user) |
231+
| `auth` | `setup`, `login`, `logout`, `status`, `list` |
232+
233+
## Guidelines
234+
235+
- Never expose or log OAuth tokens, client secrets, or keyring contents.
236+
- Confirm destructive operations (`trash`, `delete`, `archive`) with the user first.
237+
- `contacts merge` is irreversible -- always confirm before executing.
238+
- Rate limits are handled automatically with exponential backoff.
239+
- When an error mentions wrong ID prefix, check the ID Reference table.

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,6 +520,18 @@ make build
520520
- Access tokens are kept in memory only and refreshed automatically
521521
- Never commit credentials to version control
522522

523+
## AI Agent Skill
524+
525+
This repo includes an [Agent Skill](https://code.claude.com/docs/en/skills) so AI coding
526+
agents can use frontcli autonomously. Install it with:
527+
528+
```bash
529+
npx skills add dedene/frontapp-cli
530+
```
531+
532+
The skill is located at `.claude/skills/frontcli/SKILL.md` and works with Claude Code, Cursor,
533+
GitHub Copilot, and other compatible agents.
534+
523535
## Links
524536

525537
- [Front API Documentation](https://dev.frontapp.com/reference/introduction)

0 commit comments

Comments
 (0)