# Socialseal Workspace Setup > Use this skill when configuring or repairing SocialSeal for a brand, destination, market, or campaign, including "set up/onboard SocialSeal", "there is no tracking group", "create a workspace/group", "run a baseline/search journey", or when production is blocked because the requested topic has no usable SocialSeal evidence. Select or create the workspace, add groups/items, run a baseline journey, and verify exports; deliver a working setup, not merely a setup brief. - Skill: `opensealai/socialseal-workspace-setup` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add opensealai/socialseal-workspace-setup` - Raw SKILL.md: https://api.skillmd.com/api/skills/opensealai/socialseal-workspace-setup/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Marketing & Growth - License: MIT - Author: OpenSealAI (https://skillmd.com/u/opensealai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/opensealai/socialseal-workspace-setup --- # SocialSeal Workspace Setup ## Overview SocialSeal is a social-search intelligence platform. It helps teams understand what appears when people search on social and AI-search surfaces, and whether a brand, competitor, creator, or content pattern is discoverable for the right keywords. A setup task is complete only when the workspace can produce usable data. A document is not the deliverable. The deliverable is a configured workspace with the right tracking groups, tracking items, baseline runs, and exports verified. ## Core Concepts | Concept | Meaning | | --- | --- | | Workspace | Top-level SocialSeal container for one brand, client, or project. Tracking groups and exports are scoped to a workspace. | | Tracking group | A measurement container for one platform and one coherent keyword/topic scope. Example: `TikTok / US / category searches`. | | Tracking item | A single item inside a group, usually a search keyword with region/platform metadata. | | Search journey | A keyword-expansion or evidence run for a subject, subject type, and region. Useful for generating or validating keyword coverage before/after group creation. | | Export | CSV/JSON output used by downstream analysis skills. Key export types include enriched search results and group evidence. | ## When to Use Use this skill for: - New workspace onboarding. - Selecting and validating an existing workspace. - Creating tracking groups. - Adding keyword tracking items to groups. - Running baseline search journeys. - Confirming that group evidence and enriched search-result exports work. Do not use this skill for opportunity analysis, creator briefs, social plans, or measurement readouts. Those are downstream tasks that depend on a correctly configured workspace. ## Inputs ### Required - SocialSeal CLI access or SocialSeal MCP server access. - Workspace target: existing workspace ID/name, or enough context to identify the intended workspace. - Brand or subject name. - Target platform(s): use platform values supported by SocialSeal, commonly `tiktok`, `instagram`, `youtube`, `ig_reels`, `yt_shorts`, `douyin`, `xhs`, or `google_ai`. - Target market/region code, such as `US`, `GB`, `JP`, `SG`, `MY`. - At least one keyword/topic set to track. ### Good to have - Owned social handles. - Competitor handles or competitor brand names. - Local-language keyword variants. - Whether each group is branded, category, competitor, creator, or campaign tracking. - Reporting cadence and expected downstream deliverable. ### If the user is terse If the user only says something like “set up SocialSeal for this brand,” ask for the minimum missing setup inputs: 1. workspace or workspace name 2. market/region 3. platform(s) 4. brand/subject 5. seed keyword/topic list If the workspace already exists and you can list workspaces, do that before asking. ## Tooling Both MCP and CLI work. Prefer MCP when available: discover with `socialseal_list_workspaces` and `socialseal_list_available_tools`, read `socialseal_get_tool_schema` before mutating calls, then `socialseal_call_tool`. The CLI mirrors this with `tools list` / `tools schema` / `tools call`. See `references/mcp-and-cli-usage.md`. ## CLI Setup Workflow Use `npx -y @socialseal/cli` unless the `socialseal` binary is already installed. Prefer machine-readable flags when available. ### 1. Discover the current CLI surface Run these first. Do not rely on stale command memory. ```bash npx -y @socialseal/cli --help npx -y @socialseal/cli workspace --help npx -y @socialseal/cli tools --help npx -y @socialseal/cli data --help ``` Then inspect the relevant tool schemas: ```bash npx -y @socialseal/cli tools list npx -y @socialseal/cli tools schema --function group-management npx -y @socialseal/cli tools schema --function search-journey-run npx -y @socialseal/cli data export-options ``` ### 2. Select the workspace List accessible workspaces: ```bash npx -y @socialseal/cli workspace list --pretty ``` Show the current default: ```bash npx -y @socialseal/cli workspace current --pretty ``` Set the default workspace by ID, slug, or exact name: ```bash npx -y @socialseal/cli workspace use ``` If using scoped keys or automation, still pass `--workspace-id ` explicitly to later commands. This avoids accidental fallback to a personal/default workspace. ### 3. Design the group structure before creating groups Use one group per platform and coherent measurement scope. A good group name encodes platform, market, and type. Recommended group split: - `TikTok / US / category searches` - `TikTok / US / branded searches` - `Instagram / US / category searches` - `YouTube / US / category searches` - `Google AI / US / category questions` Rules: - Do not mix platforms in one group. - Do not mix branded and category keywords in one group. - Do not mix markets/languages unless the reporting question explicitly needs a combined view. - Use local-language search phrases for non-English markets. ### 4. Create a tracking group Supported platform values include `tiktok`, `instagram`, `youtube`, `ig_reels`, `yt_shorts`, `douyin`, `xhs`, and `google_ai`. ```bash npx -y @socialseal/cli tools call \ --function group-management \ --workspace-id \ --body '{"action":"create","name":"TikTok / US / category searches","platform":"tiktok","description":"Category search tracking for US TikTok keywords"}' \ --pretty ``` Save the returned numeric tracking group ID as ``. Downstream export commands use numeric group IDs, not brand-group UUIDs. ### 5. Add tracking items to the group For keyword payloads, use `group_id` and item objects. Omit item platform to inherit the group platform, or pass it explicitly if needed. ```bash npx -y @socialseal/cli tools call \ --function group-management \ --workspace-id \ --body '{"action":"add_items","group_id":,"items":[{"name":"","type":"keyword","value":"","region":"US"},{"name":"","type":"keyword","value":"","region":"US"}]}' \ --pretty ``` Use real user search language, not internal marketing phrasing. For travel/hospitality and many consumer categories, useful keywords often express planning help, comparisons, timing, location, first-timer questions, or practical detail. ### 6. Check setup completeness Use completeness to confirm expected memberships and optionally refresh visibility. ```bash npx -y @socialseal/cli tools call \ --function group-management \ --workspace-id \ --body '{"action":"completeness","group_id":,"expected_items":[{"track_type":"search","track_value":"","region":"US"},{"track_type":"search","track_value":"","region":"US"}],"include_refresh_status":true}' \ --pretty ``` Do not declare setup complete until the group has the expected items. ### 7. Run or inspect a baseline search journey A search journey helps validate subject, region, and keyword direction before or after group creation. Start a run: ```bash npx -y @socialseal/cli tools call \ --function search-journey-run \ --workspace-id \ --body '{"subject":"","subjectType":"brand","region":"US","executionMode":"async"}' \ --pretty ``` Poll an async journey run: ```bash npx -y @socialseal/cli tools status \ --kind journey_run \ --workspace-id ``` Use `subjectType: "brand"` for a brand, `"topic"` for a category/topic. If the CLI schema shows additional fields such as `locale`, `platformKeys`, `seedKeywords`, `contentPillars`, or `maxKeywords`, use them when relevant. #### Fast discovery when no tracking group exists Do not stop at "there is no group" and do not proceed with generic content. Offer: 1. **Focused one-off journey:** quickest way to discover or validate a small query set for an immediate brief. It does not create reusable tracking on its own. 2. **Reusable setup:** create clean groups/items, run the journey, refresh, and verify exports so future planning and measurement reuse the evidence. Before a journey, inspect the live `search-journey-run` schema and any exposed preflight/credit information. Show the proposed subject, region, seeds, platform scope, and focused/full option. Obtain the user's choice before consuming credits. After the run, preserve the journey output and route it to opportunity analysis; do not reduce it to a list of hashtags. ### 8. Verify export data flow List export options: ```bash npx -y @socialseal/cli data export-options ``` For enriched ranked search rows: ```bash npx -y @socialseal/cli data export-search-results \ --group-ids \ --workspace-id \ --out ./exports/search-results-.csv \ --timeout 120000 ``` For group evidence that automatically routes social and Google AI groups to the correct export shape: ```bash npx -y @socialseal/cli data export-group-evidence \ --group-id \ --workspace-id \ --out ./exports/group-evidence-.csv \ --timeout 120000 ``` A valid setup should produce a file with usable rows or a clear, explainable reason for no rows, such as a new group with no completed refresh yet. ## MCP Setup Workflow Use the same logical workflow through MCP. Do not invent MCP tool names. 1. List available MCP tools from the SocialSeal server. 2. Identify tools corresponding to: - workspace list/current/select - tool/function schema or help - tracking group creation - tracking item add/bulk add - group completeness/status - search journey start/status - search results or group evidence export 3. Read tool schema before calling mutating actions. 4. Create one group first, add a small keyword set, and verify completeness before bulk creation. 5. Export evidence after setup to confirm the workspace produces downstream data. If MCP lacks a setup operation that the CLI supports, use the CLI for that operation and continue with MCP for reads/exports. ## Done Means Workspace setup is done only when all of these are true: - Correct workspace selected and confirmed. - Planned tracking groups created with the correct platform values. - Tracking items added to each group. - Completeness check confirms expected items. - At least one baseline search journey or status check has run for the workspace. - At least one export command works for each important group type, or the reason for no rows is documented. - Workspace ID, group IDs, group names, platform, market, and keyword set are recorded for downstream skills. ## Do / Don't ### Do - Use `workspace list` before setup if the workspace is not explicitly provided. - Use `tools schema --function group-management` before creating or adding items. - Use `group_id`, not `groupId`, in `group-management` bodies unless the live schema says otherwise. - Use `--group-ids` for `export-search-results` and `--group-id` for `export-group-evidence`. - Keep a raw setup log with commands run, returned IDs, and export file paths. - Create and validate one group first, then scale the pattern. ### Don't - Don't call the output a brief when the user asked for setup. - Don't mix platforms or keyword types inside one group. - Don't add English-only keywords for non-English markets unless the user's scope is English-language search. - Don't use brand-group UUIDs where the CLI expects numeric tracking group IDs. - Don't treat a header-only export as success without explaining why no rows exist. - Don't expose real workspace IDs, tracking IDs, API keys, or private exports in public examples. ## Troubleshooting ### Workspace not found - Run `npx -y @socialseal/cli workspace list --pretty`. - Confirm the key has access to the intended workspace. - Use `workspace use ` with ID, slug, or exact name. - Pass `--workspace-id ` explicitly on scoped commands. ### `add_items` succeeds but completeness fails - Re-check the live schema for `group-management`. - Confirm the body uses `group_id` and item objects. - Confirm the region value is valid and consistent. - Try adding a single item first to isolate malformed payloads. ### Export returns only headers or no rows - Confirm items were added with completeness. - New or modified groups may need refresh time before ranked results exist. - Try `export-group-evidence` to route the group to the correct export type. - Check date filters; too narrow a date range can hide valid results. ### Search journey does not start - Confirm required fields: `subject`, `subjectType`, `region`, and workspace context. - Use `subjectType: "topic"` for category searches, not `brand`. - Add `executionMode: "async"` for long runs and poll with `tools status`. ### MCP and CLI disagree - Prefer the live schema from the surface you are using. - Record which surface created each group/item. - If a mutating MCP call is missing or unstable, use the CLI for setup and MCP for inspection/exports. ## Verification Checklist - [ ] Correct workspace selected or identified. - [ ] Group structure matches platform × market × keyword type plan. - [ ] Groups created with valid platform values. - [ ] Items added using schema-valid payloads. - [ ] Completeness confirms expected tracking items. - [ ] Baseline journey/status was run or intentionally skipped with reason. - [ ] If the topic initially lacked a group, the one-off versus reusable choice and any credit approval are recorded. - [ ] Exports tested and saved for downstream use. - [ ] Setup log includes workspace ID, group IDs, group names, platforms, markets, and export paths. - [ ] No private IDs or credentials appear in public/shared docs.