Pp Slack — Workflow

Overview

How the pp-slack skill works, step by step.

Source Workflow

Codex skill workflow.

Step-by-step Workflow

Slack - Printing Press CLI

Prerequisites: Install the CLI

This skill drives the slack-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer:

   npx -y @mvanhorn/printing-press install slack --cli-only
   

2. Verify: slack-pp-cli --version
3. Ensure $GOPATH/bin (or $HOME/go/bin) is on $PATH.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

go install github.com/mvanhorn/printing-press-library/library/productivity/slack/cmd/slack-pp-cli@latest

If --version reports "command not found" after install, the install step did not put the binary on $PATH. Do not proceed with skill commands until verification succeeds.

When to Use This CLI

Reach for this when the user wants:

• send a Slack message to a channel or DM
• search Slack across channels, DMs, and threads (live or synced)
• list users, channels, usergroups, custom emoji, pinned items, or reminders
• understand channel health (quiet channels, activity trends, response times, digest)
• find stale or unanswered threads across the workspace
• pull an activity summary for a user or channel
• export channel history to JSONL for archival or migration
• discover the funniest messages in public channels (local-sync-powered novelty query)

Skip it when the user wants to create Slack apps, workflows, or manage admin-only team settings beyond team access logs. Those surfaces are better served by the Slack web admin.

Two Auth Surfaces

Slack has two parallel token types and this CLI supports both:

Set whichever the workspace permits. If both are set, user-token wins for user-scoped endpoints and bot-token otherwise. Get a token at https://api.slack.com/apps -> your app -> OAuth & Permissions.

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help -> show slack-pp-cli --help
2. Starts with install -> ends with mcp -> MCP installation; otherwise -> CLI installation
3. Anything else -> Direct Use (map to the best command and run it)

MCP Server Installation

The CLI also ships an MCP server at slack-pp-mcp. Install and register:

go install github.com/mvanhorn/printing-press-library/library/productivity/slack/cmd/slack-pp-mcp@latest
claude mcp add -e SLACK_BOT_TOKEN=xoxb-... slack-pp-mcp -- slack-pp-mcp

Ask the user for the actual token value before running.

Direct Use

1. Check installed: which slack-pp-cli. If missing, offer CLI installation.
2. Discover commands: slack-pp-cli --help; drill into slack-pp-cli <cmd> --help.
3. Match the user query to the best command (see Notable Commands below).
4. Execute with --agent for structured output:

   slack-pp-cli <command> [args] --agent
   

5. The --agent flag sets --json --compact --no-input --no-color --yes.

Source routing (local vs live) is controlled by --data-source: auto (default) prefers local-synced data with live fallback; live always hits the API; local runs fully offline against the SQLite snapshot. Run slack-pp-cli sync first to populate the local store for analytics queries.

Notable Commands

Run any command with --help for full flag documentation.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr
• Filterable — --select keeps a subset of fields, with dotted-path support (see below)
• Previewable — --dry-run shows the request without sending
• Cacheable — GET responses cached for 5 minutes, bypass with --no-cache
• Non-interactive — never prompts, every input is a flag

Filtering output

--select accepts dotted paths to descend into nested responses; arrays traverse element-wise:

slack-pp-cli <command> --agent --select id,name
slack-pp-cli <command> --agent --select items.id,items.owner.name

Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.

Response envelope

Data-layer commands wrap output in {"meta": {...}, "results": <data>}. Parse .results for data and .meta.source to know whether it's live or local. The N results (live) summary is printed to stderr only when stdout is a TTY; piped/agent consumers see pure JSON on stdout.

Exit Codes

Execution Logic

The skill executes when its trigger fires (slash command, natural-language match, or direct invocation). It reads its references, applies its rules, and produces the documented outputs.

Edge Cases

See the source skill's references/ and scripts/ folders for edge-case handling.

Failure Handling

A skill failure surfaces as a tool error or a partial output; never a silent skip. Re-run with --verbose (where applicable) for diagnostics.

Integration Notes

• Claude — invoked via the Skill tool with skill: "pp-slack".
• Codex — referenced from AGENTS.md if mirrored.
• Antigravity — referenced from the workspace agent rules if mirrored.
• HQ Project — listed on the landing page Skills section + post-login sidebar.
• MD Project (md.sgnk.ai) — file rendered from Skills/Pp Slack/workflow.md.
• Obsidian — file rendered with frontmatter + tags.

Usage Examples

Invoke via slash command or natural language matching the skill description.

Source: (none)