Instagram Audience Voice

# Instagram Audience Voice

Follow shared public skill rules in:

- `postplus-shared` public skill rules

Use this skill when the user wants to:

- understand what people say in Instagram comments
- extract pain points, objections, and FAQs
- find real language for ads, captions, or scripts
- compare audience reaction across shortlisted content

Read these references before implementation:

- `skills/20-research/instagram-references/actor-selection.md`
- `skills/20-research/instagram-references/normalized-schema.md`
- `skills/20-research/instagram-references/tool-contracts.md`

## Primary Hosted Collection Key

- `instagram-comments`

## Entry Requirement

Do not start from a huge blind set of posts.

Prefer one of these first:

- benchmark shortlist from `instagram-content-benchmark`
- manually provided post URLs
- a small set of competitor top posts

## Recommended Workflow

1. collect comments from a shortlisted set of posts or reels
2. normalize comments
3. cluster comments by theme and intent
4. separate high-signal language from low-signal reactions
5. summarize actionable audience voice

## Public Skill Execution Contract

- keep shortlisted post inputs, raw comment datasets, normalized outputs, and
  clustering caches under `<work-folder>/.postplus/instagram-audience-voice/`
- keep only final user-facing summaries or reusable copy notes outside
  `.postplus/`
- start from a bounded first pass:
  - a small shortlist of posts
  - one or two themes
  - comments only after the shortlist exists
- if PostPlus Cloud service is unavailable, unauthorized, or returns a stable
  network error, stop immediately instead of switching to ad hoc shell glue

## Good Output

Return:

- top comment themes
- repeated questions
- objections or skepticism
- purchase or trial intent signals
- exact phrases worth reusing in copy
- comments that suggest unmet needs

## Suggested Buckets

- praise
- objection
- question
- purchase-intent
- request-for-details
- low-signal / meme

## Handoff

Escalate to campaign or content strategy workflows when:

- the user wants to turn audience language into hooks, offers, or creative briefs


import {
  mkdirSync,
  readFileSync,
  realpathSync,
  writeFileSync,
} from "node:fs";
import { dirname } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";

export function parseArgs(argv) {
  const args = {};

  for (let index = 0; index < argv.length; index += 1) {
    const current = argv[index];

    if (!current.startsWith("--")) {
      continue;
    }

    const key = current.slice(2);
    const next = argv[index + 1];

    if (!next || next.startsWith("--")) {
      args[key] = true;
      continue;
    }

    args[key] = next;
    index += 1;
  }

  return args;
}

export function readJson(filePath) {
  return JSON.parse(readFileSync(filePath, "utf8"));
}

export function writeJson(filePath, value) {
  mkdirSync(dirname(filePath), { recursive: true });
  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
}

export function printOrWriteJson(outputPath, value) {
  if (outputPath) {
    writeJson(outputPath, value);
    console.log(`Saved result to ${outputPath}`);
    return;
  }

  console.log(JSON.stringify(value, null, 2));
}

export function isMainModule(importMetaUrl) {
  if (!process.argv[1]) {
    return false;
  }

  try {
    return (
      realpathSync(process.argv[1]) ===
      realpathSync(fileURLToPath(importMetaUrl))
    );
  } catch {
    return importMetaUrl === pathToFileURL(process.argv[1]).href;
  }
}


#!/usr/bin/env node
import fs from 'node:fs';
import path from 'node:path';

import { requestBytes } from './network_runtime.mjs';
import {
  runHostedCapabilityEnvelopeRequest,
  runHost