project-promo-skill

name

project-promo-skill

description

Research an existing developer or open-source project from its repository, local files, documentation, official website, or release artifacts, identify why it matters to a specific reader, and turn it into a credible recommendation article, social post, cover, or persuasive 3:4 carousel. Use for 技术项目安利、开源项目宣传、GitHub/GitLab/Gitee 仓库介绍、Skill/CLI/框架/产品推荐、开源工具文章、社交媒体套图、小红书技术内容、项目发布配图, or when a user provides a project URL or local project folder and wants people to understand its use, value, evidence, fit, and next action. The visual output may use real project assets, typography, screenshots, diagrams, deterministic layout, or selective illustration; do not default to an all-AI-illustration series.

Project Recommendation and Promotion

Treat a repository as editorial source material, not as a list of features to illustrate. The primary job is to help a defined reader recognize a relevant problem, understand the project's useful transformation, trust the recommendation, judge fit, and take a low-cost next action.

The article, post copy, cover, and carousel must share one researched recommendation brief. Visual design is the final communication layer, not the starting point.

Core Outcome

Given a technical project with verifiable first-party material, answer five reader questions:

1. Why is this relevant to my current work?
2. What useful change does it make possible?
3. What does using it actually look like?
4. Why should I believe the recommendation?
5. Is it for me, and what should I do next?

A technically accurate result that does not create relevance, understanding, trust, or action is incomplete.

Workflow

1. Research the repository

Inspect the available project source before positioning it. Prefer first-party material: repository files, README, docs, examples, package metadata, source structure, releases, license, official website, screenshots, demos, and author-provided assets. For a hosted repository URL, use the connected first-party source when available.

Separate:

• verified capabilities;
• project claims that require attribution;
• concrete commands, inputs, outputs, and workflows;
• evidence and credibility signals;
• limitations, prerequisites, license constraints, and non-fit cases;
• visual assets that can appear in the final content.

Never invent metrics, versions, compatibility, privacy guarantees, commands, outputs, or comparisons. Read references/repository-intelligence.md.

2. Classify the repository

Choose the dominant type because each requires a different recommendation story:

Type	Reader's main question	Default narrative
Agent Skill	When does it trigger and what work does it perform?	situation → trigger → workflow → result
CLI / developer tool	What repeated pain does one command remove?	pain → command → transformation → use cases
Library / framework	What can I build or integrate differently?	engineering problem → API/mechanism → example → trade-off
End-user product	What changes in the user experience?	situation → product flow → outcome → fit
Infrastructure	Is the technical advantage worth adoption cost?	scale problem → mechanism → evidence → constraints
Content repository	What knowledge gap does it close?	information need → organization → useful entry points

Do not force every repository into what it is → features → audience → install.

3. Build the recommendation brief

Create this internal source of truth before writing copy or choosing a visual style:

project:
  name:
  category:
  one_line_definition:
reader:
  primary_audience:
  current_situation:
  recurring_pain:
  desired_outcome:
recommendation:
  core_thesis:
  strongest_hook:
  before:
  mechanism:
  after:
  aha_moment:
proof:
  concrete_example:
  real_command:
  real_output:
  differentiators:
  credibility_signals:
  limitations:
adoption:
  best_fit:
  not_fit:
  setup_cost:
  next_action:

The core_thesis must connect a reader situation to a useful outcome. Avoid definitions such as “X is a powerful tool for Y” when a concrete transformation is available.

3A. Build the evidence board

Before writing card layouts, turn the research into a claim ledger, asset inventory, and evidence board. Record the project revision or evidence date, give every selected asset an evidence role, and map each decision-relevant claim to visible proof.

For a carousel of five or more cards, at least one of the first three cards must make a real project result, interface, output, repository artifact, or exact workflow dominant enough to recognize at thumbnail size. Logo-only, mascot-only, generated-object, fabricated-code, and reconstructed-UI cards do not satisfy this requirement.

Read references/evidence-board-contract.md. Narrow or remove claims that cannot receive truthful visible proof.

4. Establish the editorial angle

Write the central recommendation as:

For [specific reader in a specific situation],
this project changes [painful current state]
into [desirable new state]
through [credible mechanism],
with [evidence or boundary].

Generate several possible hooks privately, then select one with the best combination of relevance, specificity, truth, and curiosity. Prefer:

• a recognizable frustration;
• a counterintuitive insight;
• a concrete before/after;
• a surprisingly small action with a meaningful result;
• a credible contrast with the current workflow.

Reject generic section headings as primary social titles: 它是什么, 核心功能, 工作原理, 适合谁, and 快速开始 are organizational labels, not persuasive claims.

Read references/recommendation-editorial.md.

5. Write the article mother draft

Unless the user requests only a narrowly specified card, create at least a compact internal article before planning a carousel. The draft validates that the recommendation is coherent without relying on visual decoration.

Default structure:

1. concrete reader situation or tension;
2. one-sentence project introduction;
3. a complete usage example with input, action, output, and result;
4. two to four adoption-relevant differentiators;
5. evidence and important limitations;
6. fit judgment and next action.

If the user requests an article, deliver a polished version. If the user requests images only, the internal draft may remain concise, but the carousel must still inherit its argument.

6. Select the requested content package

Support these outputs from the same recommendation brief:

• recommendation article;
• social post copy;
• single cover;
• 3-card fast recommendation;
• 5–8 card complete carousel;
• technical explanation carousel;
• launch or release carousel;
• short video or spoken script.

Choose the smallest package that completes the reader journey. Do not add cards merely to fill a template. Read references/content-packaging.md.

7. Design the carousel as edited argument

Each card must advance the reader's mental state. A complete recommendation usually moves through:

recognize my problem
→ see a plausible solution
→ understand a concrete use
→ believe the value
→ judge fit
→ take action

Card titles must be publishable claims, not document navigation. A reader should understand the argument by reading titles alone.

For every card record:

• reader state before;
• claim introduced;
• proof or example shown;
• reader state after;
• visual evidence;
• exact visible copy.

Remove a card if its deletion does not reduce attention, understanding, trust, decision quality, or action.

Read references/series-storytelling.md.

8. Choose evidence before visual style

Use the strongest available visual material in this order:

1. real product UI, output, screenshot, demo frame, or repository artifact;
2. exact command, code example, configuration, data, or measurable result;
3. official logo, diagram, README image, or project asset;
4. deterministic comparison, flow, table, or typographic composition;
5. generated illustration when reality cannot communicate the idea clearly.

Do not default to a full series of generated metaphors. Generated illustration is most useful for a cover, an abstract mechanism, a project with no assets, or one distinctive continuity element.

The evidence board is a production input, not optional research notes. A selected asset must prove a result, explain a mechanism, establish verified identity, or support action. Do not shrink the strongest real result into a token while giving generic decoration the largest visual area.

9. Create project-specific art direction

Derive visual identity from the project's material, audience, emotional promise, and official assets. Preserve portfolio consistency through editorial judgment rather than a repeated template.

Stable cross-project taste:

• strong editorial point of view;
• evidence-led composition;
• deliberate typography and hierarchy;
• technically honest claims;
• controlled density and whitespace;
• project-specific visual identity;
• no decorative completion without communicative purpose.

Do not require the same pale background, ink outline, mascot, top-title/middle-scene/bottom-summary layout, or palette across unrelated projects. Read references/house-style.md and references/art-direction-grammar.md.

Write a visual thesis and privately compare three thumbnail-level directions before committing to the series. Record three verified identity anchors, two anti-template patterns, a composition-family map, and the reason the selected direction makes the recommendation easier to understand or trust. Do not ask the user to select unless the alternatives materially change positioning, evidence, or cost.

Read references/visual-thesis-contract.md. Resolve any visual contradiction with the project's own principles before rendering.

10. Select production strategy per card

• Asset-led editorial layout: real screenshots, repo assets, commands, and strong typography. This is the default for credible technical recommendation content.
• Deterministic information design: exact text, diagrams, tables, comparisons, code, or metrics.
• Hybrid: generated or sourced visual combined with deterministic typography and evidence modules.
• Illustration-led: only when one conceptual image genuinely improves understanding or emotional pull.

Never deliver a text-free illustration as a finished social card when the content plan requires a title, claim, command, or evidence. Never ask an image model to render accuracy-critical text. Treat generated visuals as source assets and complete the final card through deterministic composition.

Record an editable representation for each final card. Preserve deterministic text, selected assets, crop or annotation intent, and any generated source image separately from the flattened bitmap. A final material package must be revisable without asking an image model to recreate commands, metrics, filenames, or CTA copy.

11. Render, review, revise, and deliver

Default canvas: native 3:4 portrait, 1200 × 1600 px, unless the user specifies otherwise. Read references/canvas-contract.md.

When final rendered cards are required, run an independent visual QA loop. Read references/visual-qa-loop.md, references/qa-packet-contract.md, and agents/visual-qa.md before the first review.

1. Render every card at final size and build a review package: individual bitmaps, a contact sheet, and a per-card proof contract containing the claim, exact visible copy, verified facts, visible evidence, preserve constraints, and text-bearing component safe zones.
2. Spawn one visual QA subagent with independent context. Give it the review package, not the generation chain or the creator's self-assessment.
3. Apply every P0 and P1 repair request to the affected card only. Preserve verified claims, exact required copy, component role, and the card's intended evidence.
4. Re-render and re-review changed cards with a fresh independent reviewer context. Review the contact sheet again only after individual cards are usable.
5. Deliver only after the QA packet has no P0 or P1 issues. P2 observations are optional and must not destabilize a usable card.

Before packaging, verify every command as a copyable unit. If a command wraps visually, use explicit continuation syntax appropriate to the named shell or redesign the component so the command remains one logical line. A visually tidy but non-executable command is a P0 or P1 failure depending on whether it is the primary action.

When handing off final cards, include one concise QA summary: cards reviewed, repaired-card numbers and counts, and any residual P2 note. Do not expose the raw review packet unless the user asks for it.

If the environment cannot spawn a visual QA subagent, perform the same checklist by inspecting each actual bitmap yourself, and disclose that the independent review was unavailable. Do not substitute a contact sheet for a single-card review.

The QA loop must establish that every final card has:

• exact dimensions and consistent series ratio;
• readable and correct copy;
• no unintended text occlusion, clipping, decoration competing with critical copy, or text crossing a container boundary;
• project-specific identity;
• thumbnail-level attention and claim clarity;
• visible evidence rather than generic decoration;
• one dominant reading path;
• no unsupported claim;
• no accidental template repetition;
• a clear next action by the end of the series.

Inspect actual rendered files before delivery. Do not present a generated background, mockup, or incomplete typesetting pass as final. A QA subagent is a critic and repair guide, not a second art director: it must not rewrite facts, invent evidence, or reset the approved visual direction.

When the user requests a material pack, reusable handoff, final carousel, or launch kit, assemble and validate the package described in references/delivery-package-contract.md. Do not label a folder of PNGs plus a general caption as a complete promotional package.

Default Deliverable

When the user provides a repository and asks for a social series without further constraints, return or produce:

1. Recommendation thesis — reader, pain, transformation, proof, and boundary.
2. Compact article mother draft — enough to validate the argument.
3. Carousel architecture — usually 5–8 cards, each with a persuasive title, claim, proof, and visual evidence.
4. Visual source plan — which real assets, deterministic modules, and selective generated visuals each card uses.
5. Final rendered cards — only when the user asks for images or generation-ready output.
6. Social caption — concise post copy with project link and verified access details when relevant.
7. Evidence and source record — project snapshot, claim mapping, asset sources, and selected visual proof.
8. Material package — when requested, ordered final cards, contact sheet, mapped copy, alt text, editable sources, manifest, and concise QA summary.

If the user asks directly for images, perform the research and editorial stages internally, then continue through rendering without asking for routine approval.

Quality Gates

Score each dimension from 0 to 2. Revise below 8/10; any zero in Relevance, Comprehension, or Trust is a hard failure.

Dimension	0	1	2
Attention	no reason to continue	visually noticeable but generic	specific tension or payoff earns attention
Relevance	audience cannot recognize itself	broad audience fit	concrete reader situation is immediately recognizable
Comprehension	value remains unclear	category is clear	problem, mechanism, and outcome are clear
Trust	promotional claims without proof	some verified detail	example, evidence, and boundary support the recommendation
Action	no next step	access exists but is weak	low-cost next action is explicit and appropriate

Also reject when:

• the series reads like README headings;
• every card uses the same composition or visual metaphor;
• illustration repeats the copy without adding understanding;
• real product evidence was available but ignored without reason;
• the content explains features without showing user value;
• a beautiful cover is followed by low-information cards;
• exact text was omitted because the image model could not render it;
• a limitation important to adoption was hidden;
• the visual system looks like an unrelated project's recolored template.
• a visible P0 or P1 issue from the visual QA packet remains unresolved.
• the strongest real result was available but did not appear as dominant evidence in the first three cards of a five-or-more-card series;
• the series varies only background color while repeating the same composition family;
• a decorative device visually contradicts a principle the content recommends;
• a displayed command cannot be copied or executed because visual wrapping changed its syntax;
• a claimed material package lacks claim mapping, alt text, editable source, project revision, manifest, or an auditable QA summary.