# Socialseal Blueprint Builder

> Use this skill when the user needs evidence-backed creative best practices, a SocialSeal blueprint, reusable Video DNA patterns, or the source of truth for a brief/editor handoff. Trigger after reference examples are selected; compile their grounded practices and shot panels, handle missing_data honestly, and pass the blueprint into briefing and production.

- Skill: `opensealai/socialseal-blueprint-builder` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add opensealai/socialseal-blueprint-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/opensealai/socialseal-blueprint-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: OpenSealAI (https://skillmd.com/u/opensealai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/opensealai/socialseal-blueprint-builder

---


# SocialSeal Blueprint Builder

## Overview

A SocialSeal blueprint is the compiled, evidence-grounded answer to "what makes content win for this opportunity." It is generated from real exemplar videos, not authored from intuition. It carries `best_practices[]`, `evidence[]`, the selected exemplars, and a set of shot panels that downstream briefs and editor handoffs follow.

This skill drives `vnext-blueprints-*`. See `references/production-pipeline.md` for the end-to-end flow and `references/mcp-and-cli-usage.md` for call patterns. Use `socialseal-reference-video-analysis` first to select and analyze exemplars.

Generate only after the benchmark direction and analysis depth are approved. A
blueprint compiles evidence; it does not replace brand utility facts, asset choices,
or visual-direction approval.

## When to Use

- Generating a blueprint version for an opportunity scope.
- Reading blueprint history/versions and the latest `best_practices`/`evidence`.
- Reading shot-lift rows and pinned shot assets (the panels referenced in the editor handoff coverage table).
- Diagnosing and fixing a `missing_data` blueprint.

## Inputs

Required:
- workspace id and the opportunity `opportunityKey`
- a scope: `topic` + `pillarId`, `competitor` + `competitorBrandIds`, `tracking_group` + `trackingGroupId`, `list` + `listId` + `readinessRunId`, or `manual` + `videoUids`

Good to have:
- refinement: `pinnedVideoUids`, `excludedVideoUids`, `promotedCandidateTarget`, `retrievalPrompt` (not for manual/list)
- `platformIds`, `region`, `language`, `timePeriod`
- a `title` for the blueprint

## Workflow

1. **Confirm grounded exemplars.** Run the preview path in `socialseal-reference-video-analysis` until the promoted exemplar set is right.
2. **Generate the blueprint.** Call `vnext-blueprints-generate` (without `previewOnly`). The engine queues analysis for any promoted exemplar missing it and writes a version.
3. **Interpret status.**
   - `draft`: analysis pending. Poll until ready.
   - `generated`: ready to use.
   - `missing_data`: no qualifying evidence. The engine writes an explicit version with a reason (e.g. "no tracking group keywords found for this scope"). Do not invent practices. Fix the scope/keywords/time window and regenerate.
4. **Read the blueprint.** Use `vnext-blueprints-read` for the version's `best_practices`, `evidence`, and selected exemplars.
5. **Read shot-lift.** Use `vnext-blueprints-shots-read` to get shot panels and pinned shot assets (signed URLs). Each panel has a `panelId` used in the editor handoff coverage table.
6. **Refresh shots if stale.** Use `vnext-blueprints-shots-refresh` to requeue shot assets.
7. **Hand off.** Pass `blueprintId` (+ version) to `socialseal-creator-briefing` and the panels to `socialseal-asset-planning` for a source-clip/editor handoff.
8. **Record state.** Mark the blueprint generated, draft, or missing_data in the
   workflow manifest. Never describe a generated blueprint as finished content.

## Tool Calls (MCP-first)

Generate (tracking-group scope):

```text
socialseal_call_tool {
  "function": "vnext-blueprints-generate",
  "workspaceId": "<workspace-id>",
  "body": {
    "workspaceId": "<workspace-id>",
    "opportunityKey": "<opportunity-key>",
    "scopeType": "tracking_group",
    "trackingGroupId": <group-id>,
    "timePeriod": "30d",
    "promotedCandidateTarget": 12,
    "title": "<blueprint-title>"
  }
}
```

Read the latest version and shot-lift:

```text
socialseal_call_tool { "function": "vnext-blueprints-read", "workspaceId": "<workspace-id>", "body": { "opportunityKey": "<opportunity-key>" } }
socialseal_call_tool { "function": "vnext-blueprints-shots-read", "workspaceId": "<workspace-id>", "body": { "blueprintId": "<blueprint-id>", "signedUrlSeconds": 3600 } }
```

CLI equivalents:

```bash
npx -y @socialseal/cli tools call --function vnext-blueprints-generate --workspace-id <workspace-id> --body @blueprint.json --pretty
npx -y @socialseal/cli tools call --function vnext-blueprints-read --workspace-id <workspace-id> --body '{"opportunityKey":"<opportunity-key>"}' --pretty
npx -y @socialseal/cli tools call --function vnext-blueprints-shots-read --workspace-id <workspace-id> --body '{"blueprintId":"<blueprint-id>"}' --pretty
```

## Output

- `blueprintId` and `version`, with `status`
- `best_practices[]` each tied to `evidence[]`; when surfacing a practice to a person, cite the exemplar by video title/URL and `@handle` and keep the `video_uid` as a traceability note
- selected exemplars with scores and matched keywords

A compiled blueprint raises confidence because its practices are grounded in multiple surfacing exemplars, but it is still an indicative pattern, not proof a given execution will perform. Frame downstream bets as testable. See `references/evidence-and-confidence.md`.
- shot panels (`panelId`, shot label, kind) and pinned shot assets
- a clear `missing_data` note and remediation when applicable

## Do / Don't

Do:
- ground every best practice in cited exemplar evidence
- reuse one `opportunityKey` across blueprint, brief, and editor handoff
- use `panelId`s to identify shots in the handoff coverage table; this does not create persisted SocialSeal mappings
- record the `blueprintId` and version for downstream skills

Don't:
- author best practices when the engine returns `missing_data`
- mix scopes in one blueprint to force a result
- edit shot panels by hand outside the engine
- expose literal workspace/blueprint IDs in shared artifacts

## Troubleshooting

- `missing_data`: widen keywords/scope, adjust `timePeriod`, or switch scope type; for competitor scope ensure `competitorBrandIds` resolve to active aliases.
- Stuck in `draft`: promoted exemplars are still analyzing; poll `vnext-blueprints-read` and `video_analysis` status.
- List scope errors (`READINESS_STALE`/`READINESS_BLOCKED`/`READINESS_WARNING_REQUIRES_OVERRIDE`): re-run list readiness; pass `allowWarningOverride` only when intentional.
- Empty shot-lift: run `vnext-blueprints-shots-refresh`, then re-read.

## Verification Checklist

- [ ] Blueprint reached `generated` (or `missing_data` was surfaced and addressed).
- [ ] Best practices are grounded in cited exemplar evidence.
- [ ] Shot panels and `panelId`s are recorded.
- [ ] `blueprintId`, version, and `opportunityKey` are handed to brief/asset skills.