Instagram Creator Discovery

# Instagram Creator Discovery

Follow shared public skill rules in:

- `postplus-shared` public skill rules

Use this skill when the user wants to:

- find Instagram creators or influencers in a niche
- search under follower-band constraints such as `5k-20k`
- find creators based on what they post, not only on bio keywords
- build creator pools for outreach or partnership research
- compare creators surfaced from search, hashtag, tagged, or content evidence

Read these references before implementation:

- `postplus-shared` research preferences
- `skills/10-routing/creator-discovery-router/references/candidate-schema.md`
- `skills/10-routing/creator-discovery-router/references/instagram-candidate-mapping.md`
- `skills/20-research/instagram-references/actor-selection.md`
- `skills/20-research/instagram-references/normalized-schema.md`
- `skills/20-research/instagram-references/tool-contracts.md`

## Core Rule

Do not default Instagram creator search to profile lookup only.

If the request cares about:

- follower bands
- recent activity
- topical fit
- audience fit

prefer a released mixed-discovery path:

1. use `instagram-search` to find candidate profiles from topical terms
2. enrich candidate profiles with `instagram-profiles`
3. optionally bring in normalized post or hashtag evidence produced by
   `instagram-content-benchmark` or `instagram-campaign-scout`
4. rank creators by profile plus any already-collected content evidence
5. return a research pool plus shortlist

## Primary Hosted Collection Keys

- `instagram-search`
- `instagram-profiles`

Released enrichment:

- hosted collection key `instagram-email-search`

## Local Tools

- `skills/20-research/instagram-tools/scripts/build_instagram_actor_input.mjs`
- `skills/20-research/instagram-tools/scripts/run_instagram_actor.mjs`
- `skills/20-research/instagram-tools/scripts/normalize_instagram_dataset.mjs`
- `skills/20-research/instagram-tools/scripts/extract_instagram_candidate_usernames.mjs`
- `skills/20-research/instagram-tools/scripts/rank_instagram_creators.mjs`

## Route Guidance

Use `handle-first` when:

- the user already has handles
- the user has competitor account lists
- the user wants profile enrichment more than discovery

Use `content-first` when:

- the user wants active niche creators
- the user cares about follower bands
- the user cares about audience fit from actual content

Use `mixed` when:

- you need search or hashtag recall first
- then need profile enrichment and creator scoring

## V1 Workflow

### 1. Build actor input from a brief

```bash
node ${CLAUDE_SKILL_DIR}/../instagram-tools/scripts/build_instagram_actor_input.mjs \
  --brief <work-folder>/.postplus/instagram-brief.json \
  --actor instagram-search \
  --output <work-folder>/.postplus/instagram-search-input.json
```

### 2. Run the collection actor

```bash
node ${CLAUDE_SKILL_DIR}/../instagram-tools/scripts/run_instagram_actor.mjs \
  --collection-key instagram-search \
  --input <work-folder>/.postplus/instagram-search-envelope.json \
  --output <work-folder>/.postplus/instagram-search-raw.json
```

The build step writes a bare actor input. Before this run step, wrap that actor
input in a `schemaVersion: 1` hosted execution envelope and pass the envelope
file to `--input`.

### 3. Normalize the dataset

```bash
node ${CLAUDE_SKILL_DIR}/../instagram-tools/scripts/normalize_instagram_dataset.mjs \
  --input <work-folder>/.postplus/instagram-search-raw.json \
  --actor instagram-search \
  --dataset-type posts \
  --output <work-folder>/.postplus/instagram-search-normalized.json
```

### 4. Extract candidate usernames

```bash
node ${CLAUDE_SKILL_DIR}/../instagram-tools/scripts/extract_instagram_candidate_usernam