Generate portfolio documentation, pitch narratives, proposals, briefs, and workbooks for any audience. Routes through a use-case registry that matches the audience and purpose to the right voice, templates, and review perspectives. Use whenever the user mentions "communicate portfolio", "portfolio documentation", "customer-facing documentation", "present portfolio", "portfolio overview", "capability overview", "service catalog", "enrich README", "repo documentation", "developer documentation", "update README with portfolio", "document the project", "open-source documentation", "GitHub README", "project overview for developers", "technical documentation from portfolio", "what do we offer", "external portfolio", "portfolio narrative", "make this customer-ready", "pitch", "portfolio pitch", "presentation narrative", "pitch deck from portfolio", "slides from portfolio", "portfolio story", "pitch for [market]", "proposal", "create a proposal", "sales proposal", "marketing brief", "market brief", "export to Excel", "spreadsheet", "XLSX", "workbook", "portfolio workbook", "send to Excel", "download portfolio", "collateral", "deliverable", or wants to turn internal portfolio data into something any audience can read, present, or analyze — even if they don't say "communicate" explicitly. Also trigger when the user asks "how do I present this", "how do I document this", or "how do I export this".
From cogni-portfolionpx claudepluginhub cogni-work/insight-wave --plugin cogni-portfolioThis skill is limited to using the following tools:
references/templates-customer-narrative.mdreferences/templates-market-brief.mdreferences/templates-pitch.mdreferences/templates-proposal.mdreferences/templates-repo-documentation.mdreferences/use-case-registry.mdProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Builds 3-5 year financial models for startups with cohort revenue projections, cost structures, cash flow, headcount plans, burn rate, runway, and scenario analysis.
The single output skill for the portfolio pipeline. Transforms portfolio entities into anything an audience needs — documentation, pitch narratives, proposals, marketing briefs, or data workbooks. It routes through a use-case registry that matches the audience and purpose to the right voice, templates, and review perspectives.
Internal portfolio data (slugs, TAM/SAM/SOM, relevance tiers, quality scores) is never what an audience sees. What they need depends on who they are and how they'll consume it:
| Use Case | Audience | Output | Format |
|---|---|---|---|
customer-narrative | Buyers, executives | Value-led documentation for self-paced reading | Markdown |
repo-documentation | Developers, OSS community | Technical clarity: what, how, getting started | Markdown |
pitch | Executives, conference, board | Arc-structured presentation narrative (cogni-narrative compatible) | Markdown with arc_id |
proposal | Sales teams, prospects | Per-proposition sales proposal | Markdown |
market-brief | Marketing teams | Market content package with sizing, buyer profile, messaging | Markdown |
workbook | Leadership, analysts | Structured spreadsheet with all portfolio data | XLSX |
| Custom/ad-hoc | Any audience | User-defined voice, sections, review | Markdown |
Each use case defines its own voice, output templates, and review criteria. The pitch use case is unique: its output includes arc_id in frontmatter, making it directly consumable by story-to-slides, story-to-web, story-to-big-picture, and story-to-storyboard — no intermediate /narrative step needed.
Verify the portfolio is sufficiently complete before generating:
bash $CLAUDE_PLUGIN_ROOT/scripts/validate-entities.sh "<project-dir>"
bash $CLAUDE_PLUGIN_ROOT/scripts/project-status.sh "<project-dir>"
Minimum requirements:
portfolio.json has company context filled inIf cogni-claims/claims.json exists, check claim verification status. Warn about unverified claims and recommend running the verify skill first. Allow the user to proceed — handle unverified claims according to the use case (customer-narrative: omit silently; repo-documentation: include with [unverified] marker; ad-hoc: ask the user).
Read references/use-case-registry.md for the full registry of available use cases. Also check for communicate-use-cases.json in the project root for user-defined custom use cases.
Infer the use case from the user's request. Match against trigger phrases and context from the registry. Inference priority:
repo-documentation)communicate-use-cases.json for custom use cases whose audience/name matchesIf the request is ambiguous, present options:
"What do you want to use the portfolio content for?"
- Pitch narrative — arc-structured presentation narrative, ready for story-to-slides (company presents to audience)
- Customer narratives — website content, sales materials, executive briefings (company speaks to buyer)
- Proposals — per-proposition sales proposals for specific Feature × Market pairs
- Marketing briefs — market content packages with sizing, buyer profile, messaging themes
- Portfolio workbook — XLSX spreadsheet with all portfolio data for analysis
- Repository documentation — README enrichment, plugin overviews, getting-started guides (project speaks to developer)
- {any custom use cases from communicate-use-cases.json}
- Something else — describe your purpose and I'll help shape the output
If the user selects "something else", follow the ad-hoc flow (see Ad-Hoc Use Cases below).
Load the scope options from the selected use case (see registry). Only ask for clarification if genuinely ambiguous.
For customer-narrative: overview, market (which one?), customer (which market and persona?), or all.
For pitch: market (which one?), overview (portfolio-wide), or all.
For proposal: single (which proposition?), market (all propositions in a market), or all.
For market-brief: single (which market?), or all.
For workbook: full (all sheets), or matrix (proposition matrix only).
For repo-documentation: readme-enrichment, plugin-overview, use-case-gallery, or all.
For custom/ad-hoc use cases: use the scopes defined in the use case configuration.
If the request is vague, present the scope options from the selected use case.
Read entity files from the project directory. Which entities to load depends on the use case and scope:
All use cases:
portfolio.json for company context and languageproducts/*.json, features/*.jsonCustomer-narrative (all scopes):
propositions/*.json (filter by market for tailored views)solutions/*.json and packages/*.json (if available)markets/*.json and customers/*.json (for tailored views)competitors/*.json (for differentiation, woven into narrative)Pitch:
markets/{market-slug}.json (or all markets for overview/all scopes)propositions/{feature}--{market-slug}.json for the target market(s)customers/{market-slug}.json for pain points (Why Change)competitors/{feature}--{market-slug}.json for differentiation (Why You)solutions/{feature}--{market-slug}.json and packages/{product}--{market-slug}.json for pricing (Why Pay)$CLAUDE_PLUGIN_ROOT/scripts/project-status.sh for relevance tierscogni-narrative/skills/narrative/references/story-arc/{arc-id}/arc-definition.mdurgency: "Act" for Why Now)Proposal:
$CLAUDE_PLUGIN_ROOT/scripts/project-status.sh for relevance tiers (when batch generating)Market-brief:
Workbook:
Repo-documentation:
propositions/*.json (for value framing and breadth indicators)markets/*.json (for use-case derivation)customers/*.json (for persona-based scenario descriptions)Ad-hoc/custom: Load all entities by default, let the generation step filter what's relevant.
Internal context (optional): If context/context-index.json exists, read relevant entries. Strategic context enriches company positioning. Competitive context sharpens differentiation.
Load the template file for the selected use case from the registry's template reference. For built-in use cases:
customer-narrative -> read references/templates-customer-narrative.mdpitch -> read references/templates-pitch.mdproposal -> read references/templates-proposal.mdmarket-brief -> read references/templates-market-brief.mdworkbook -> no template; prepare structured data and delegate to document-skills:xlsx skill (fallback to CSV)repo-documentation -> read references/templates-repo-documentation.mdFor custom use cases, generate section structure based on the use case's voice, scopes, and audience fields — no separate template file is needed.
For ad-hoc use cases, use the parameters collected during the ad-hoc flow.
Citation rule: All templates require citations to link to external source URLs from entity evidence[].source_url fields. Never generate citations that link to internal JSON file paths (e.g., propositions/x.json). When an evidence claim has no external URL, present it as an inline estimate without a citation. See each template's Citations section for format details.
Blueprint metadata is internal. Solutions may carry blueprint_ref and blueprint_version fields — these track delivery pattern consistency and are used by the solutions skill for drift detection. Never expose blueprint metadata in customer-facing output (proposals, pitches, customer narratives). It is acceptable to reference the delivery structure itself (phases, timelines) since that comes from the solution content, but not the blueprint versioning mechanism.
Output path: Write to output/communicate/{use-case-id}/ followed by the scope-specific filename from the template.
Backward compatibility: If old-format files exist at output/communicate/portfolio-overview.md (without use-case subdirectory), mention that the output structure has changed and that new files will be in output/communicate/customer-narrative/. Do not automatically migrate or delete old files.
After generating output, delegate to the communicate-review-assessor agent for quality assessment. The assessor adapts its perspectives based on the use case.
Spawn the agent with:
customer-narrative, repo-documentation, or custom ID)overview, readme-enrichment, etc.)For ad-hoc and custom use cases, also pass the review perspectives defined during the ad-hoc flow or in the custom use case's review.perspectives array.
Processing the verdict:
accept (all perspectives score 85+): The document is ready. Store the review JSON and proceed to step 5. Surface any optional_improvements from the synthesis to the user.
revise (all perspectives score 70+ but not all 85+):
revision_guidance and critical_improvements from the review JSONreject (any perspective below 50): Surface the full assessment to the user. Do not auto-retry. Ask whether to regenerate from scratch or address specific issues manually.
Interactive vs batch mode:
Skipping review: Some ad-hoc use cases may not need formal review. If the user indicated review is not needed during the ad-hoc flow, skip this step and go directly to step 5.
Store review results alongside each generated file:
output/communicate/{use-case-id}/{filename}.review.jsonThe review JSON contains all rounds with timestamps and final verdict:
{
"skill": "portfolio-communicate",
"use_case": "customer-narrative",
"assessor": "communicate-review-assessor",
"rounds": [
{ "round": 1, "verdict": "revise", "overall_score": 74, "timestamp": "...", "full_assessment": { "..." } },
{ "round": 2, "verdict": "accept", "overall_score": 87, "timestamp": "...", "full_assessment": { "..." } }
],
"final_verdict": "accept",
"final_score": 87
}
List generated files with paths AND their review status.
If all files accepted, show per-file review scores, then suggest the downstream pipeline appropriate for the use case:
For customer-narrative:
/copywrite on any generated file to polish for executive readability"/narrative --source-path output/communicate/customer-narrative/... to transform into an arc-driven executive narrative"/story-to-web for landing pages, /story-to-slides for presentations, /story-to-big-picture for visual journey maps/marketing-setup and used as voice/messaging enrichment when generating marketing content — ensuring consistency between how you present your portfolio and how your marketing speaks to the same audience"For pitch:
/narrative-review to score against the arc's quality gates"/copywrite to polish for executive readability while preserving arc structure"/story-to-slides → PowerPoint presentation/story-to-web → scrollable landing page/story-to-big-picture → illustrated visual journey map/story-to-storyboard → multi-poster print storyboard/why-change to add web research, customer-specific context, and TIPS enrichment for a deal-ready version"For proposal:
/copywrite to polish for buyer readability"For market-brief:
/copywrite to polish"/content-strategy"For workbook:
For repo-documentation:
/copywrite to polish for readability"output/communicate/repo-docs/readme-sections.md into your project's README"For custom/ad-hoc use cases: suggest downstream steps from the use case's downstream field, or recommend /copywrite as a safe default.
If any files in revise after max rounds: Show remaining issues per file. Suggest targeted manual edits before downstream pipeline.
If any files rejected: Block downstream suggestions for those files. Show diagnosis with specific failure points. Suggest regeneration or manual intervention.
Save as custom use case (ad-hoc only): If this was an ad-hoc run, offer: "Would you like to save this configuration as a reusable use case? Next time you can just reference it by name." If yes, write to communicate-use-cases.json in the project root (create the file if it doesn't exist; append to the use_cases array if it does).
When the user selects "something else" or describes a purpose that doesn't match any registered use case, guide them through defining the parameters:
1. Audience: "Who will read this?" Suggest common options based on what the portfolio contains:
2. Voice/Tone: "How should it sound?" Suggest based on the audience:
3. Sections: "What sections do you need?" Suggest a structure based on the audience:
4. Review: "Should we review the output quality?" Suggest appropriate perspectives based on the audience. If the user wants review, ask from whose perspective (or suggest based on audience). If the user skips review, generation still runs but step 4 is skipped.
5. Generate using the collected parameters. The voice, sections, and entity selection follow from the audience definition. Write output to output/communicate/ad-hoc/ (or a user-chosen directory name).
6. Persist (optional): After generation, offer to save as a reusable custom use case.
output/communicate/{use-case-id}/use_case fieldportfolio.json language field. Generate content in that language if present, default to Englishportfolio.json has a language field, communicate with the user in that language. Technical terms, skill names, and CLI commands remain in Englishreferences/use-case-registry.md — Registry of available use cases with trigger phrases, voice profiles, scope options, and review configurationreferences/templates-customer-narrative.md — Templates for customer-facing narratives (overview, market, customer)references/templates-pitch.md — Templates for arc-structured pitch narratives (cogni-narrative compatible)references/templates-proposal.md — Templates for per-proposition sales proposalsreferences/templates-market-brief.md — Templates for per-market marketing briefsreferences/templates-repo-documentation.md — Templates for developer-facing content (readme-enrichment, plugin-overview, use-case-gallery)communicate-review-assessor — Use-case-aware stakeholder review for output quality. Adapts perspectives based on the use case: buyer/marketing/sales for customer narratives, developer/maintainer/writer for repo documentation, custom perspectives for ad-hoc use cases.