← Back to Skills

slack-conversation-read

active

Explains and parses the conversation.json schema produced by slack-vault-sync. Use when reading extracted/slack/[channel]/conversation.json — explains the schema (nested threads, files, reactions) so you don't have to reverse-engineer it from the raw JSON. Trigger on "read the Slack conversation.json", "parse extracted/slack", or when a channel's synced content needs to be scanned for facts. Do NOT use for producing conversation.json in the first place (see slack-vault-sync) or for reading live Slack via API/MCP.

Owner: velais Category: workflow-automation Version: 1.0.0 Tokens: ~1k
slackjsonparsingclient-feedback
84

Quality Score Breakdown

Structure (15%) 18/18
Show checks (11)
  • ✓ SKILL.md exists with exact casing 3/3
  • ✓ Valid YAML frontmatter 3/3
  • ✓ No unexpected frontmatter keys 1/1
  • ✓ Name field valid (kebab-case) 2/2
  • ✓ Name matches folder name 1/1
  • ✓ Description field present 2/2
  • ✓ No angle brackets in frontmatter 1/1
  • ✓ Folder name is kebab-case 1/1
  • ✓ No README.md inside skill folder 1/1
  • ✓ Test directory with test-cases.yml exists 2/2
  • ✓ Status 'active' is valid 1/1
Description (20%) 18/22
Show checks (7)
  • ✗ No action verbs found — description should say what the skill DOES 0/4
  • ✓ Contains trigger indicators: use when, use for, trigger 5/5
  • ✓ Description is specific and actionable 4/4
  • ✓ File types mentioned in description 3/3
  • ✓ Description length: 518/1024 chars 2/2
  • ✓ Has negative triggers (scope boundaries) 2/2
  • ✓ Owner/author specified in metadata 2/2
Instructions (25%) 14/28
Show checks (8)
  • ✓ Skill body has content 3/3
  • ✗ Add numbered steps, ## headers, or clear sequence to instructions 0/4
  • ✓ Includes examples 5/5
  • ✗ Add error handling — what should happen when things fail? 0/4
  • ✗ Consider moving detailed docs to references/ for better token efficiency 0/4
  • ✗ Instructions could be more actionable — use 'Run X', 'Call Y', 'Check Z' 1/3
  • ✓ Word count: 221/5000 2/2
  • ✓ All referenced paths exist 3/3
Test Coverage (25%) 29/29
Show checks (10)
  • ✓ test-cases.yml exists and parses 3/3
  • ✓ 4 should-trigger tests ✓ 4/4
  • ✓ 4 should-not-trigger tests ✓ 3/3
  • ✓ 3 functional tests ✓ 5/5
  • ✓ 1 negative tests ✓ 3/3
  • ✓ 1 edge case tests ✓ 3/3
  • ✓ Performance baseline documented 2/2
  • ✓ All functional tests have ≥2 assertions 2/2
  • ✓ All trigger phrases are diverse 2/2
  • ✓ All assertions are specific 2/2
Security (15%) 15/15
Show checks (5)
  • ✓ No secrets detected 5/5
  • ✓ No injection vectors in frontmatter 3/3
  • ✓ Name is not reserved 3/3
  • ✓ No suspicious code patterns 2/2
  • ✓ External URLs: 0 2/2

Suggestions

  • → Move detailed reference material to references/ and link from SKILL.md
  • → Add more functional tests — aim for 4-5 covering common scenarios and edge cases

Test Coverage

4
Should Trigger
4
Should Not Trigger
3
Functional
1
Negative
1
Edge Cases
No
LLM Evals

Reading conversation.json

One file per channel, written by slack_sync.py (skill slacksync). Never edit by hand.

{
  "channel": { "id", "name", "slug", "type", "archived", "purpose" },
  "workspace": "team name",
  "sync": { "last_run_at", "last_mode", "message_count", "root_count" },
  "messages": [                       // root messages only, chronological
    {
      "ts": "1785839131.803679",      // Slack message id — sort/dedupe key
      "iso": "2026-08-04T10:25:31+00:00",
      "user": { "id", "name", "email" },
      "type": "message", "subtype": null,  // subtype e.g. "channel_join" = system message, not content
      "text": "…",
      "reactions": [{ "name", "count" }],
      "files": [{ "id", "name", "mimetype", "size",
                  "local_path",        // relative to the channel dir — null if not downloaded
                  "status" }],         // "downloaded" | "missing" | "pending"
      "reply_count": 3,                // null if no thread
      "replies": [ { …same shape… } ]  // thread replies nested HERE, not flat in messages[]
    }
  ]
}

How to read it:

  • Skip messages with subtype set (joins/renames/etc.) unless you’re specifically after channel history — they’re not client content.
  • A message’s thread replies are in its own replies[], not later in the top-level messages array — walk both levels.
  • files[].local_path is null until downloaded; check status before assuming the attachment is on disk. Missing ones are listed in files/MISSING.md next to the JSON.
  • ts is the stable identity — use it (not array position) when citing or cross-referencing a message.