agentleFS
CarlosZieglerCarlosZiegler/zietec-skills/skills/design/product-studio/SKILL.md

product-studio

Skill1 starsChanged 52 days agoMITView on GitHub

Run a persistent product-and-design operating system for multi-session website, app, brand, and digital-product work. Use when ChatGPT should maintain durable design state across sessions or agents, organize research and decisions, coordinate Design Maestro and specialist skills, create or update a .design workspace, manage design territories and human decisions, run readiness/quality gates, and produce implementation handoffs without losing product rationale. JEV/TypeSafe AI and Firecrawl are optional accelerators, never hard dependencies.

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

43 rules. About 0 are common, 29 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈29

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use Product Studio for persistence and lifecycle management.

    line 14
  2. Distinctive:

    Use Design Maestro for creative orchestration and design judgment.

    line 15
  3. Distinctive:

    Use specialist skills for domain depth.

    line 16
  4. Distinctive:

    If Design Maestro is unavailable, continue with the Product Studio workflow and apply the same product-first principles, but do not claim …

    line 25
  5. Very specific:

    Treat .design/ as the durable source of truth for product/design decisions when a working directory exists.

    line 29
  6. Very specific:

    Never replace approved decisions silently.

    line 30
  7. Distinctive:

    Do not dump chat transcripts into the workspace.

    line 31
  8. Distinctive:

    Keep product strategy, brand, UX, content, and implementation constraints connected.

    line 34
  9. Very specific:

    Read existing .design/ state before proposing changes.

    line 39
  10. Distinctive:

    Prefer small, explicit updates to the workspace after each meaningful phase.

    line 40
  11. Distinctive:

    When a working directory is available, use this project-local structure:

    line 44
  12. Very specific:

    Use scripts/init_design_workspace.py to create missing files without overwriting existing work.

    line 63
  13. Very specific:

    Read references/design-state.md for ownership and update rules.

    line 65
  14. Very specific:

    Read BRIEF.md, PRODUCT.md, DESIGN.md, DECISIONS.md, and QA.md first.

    line 71
  15. Distinctive:

    Read other files only as needed for the current task.

    line 72
  16. Distinctive:

    Create the smallest useful product frame.

    line 80
  17. Very specific:

    Run in conversational mode.

    line 85
  18. Very specific:

    Update BRIEF.md only when the project frame materially changes.

    line 101
  19. Distinctive:

    Do not jump to visual styling when product logic is unresolved.

    line 116
  20. Distinctive:

    Use research only when it can change a product/design decision.

    line 120
  21. Distinctive:

    Use normal web/search first.

    line 131
  22. Distinctive:

    If JEV is available, it may rerank/classify research fragments before synthesis.

    line 133
  23. Distinctive:

    Use Design Maestro for creative exploration when available.

    line 152
  24. Distinctive:

    Do not treat palette swaps as separate territories.

    line 177
  25. Very specific:

    When a choice is made, append to DECISIONS.md:

    line 183
  26. Distinctive:

    Do not hide a creative choice behind a JEV score.

    line 194
  27. Distinctive:

    Document intent and roles, not only raw pixels.

    line 226
  28. Distinctive:

    Use specialist skills for interaction, adaptation, Apple-platform guidance, or accessibility as needed.

    line 243
  29. Distinctive:

    After implementation feedback, user testing, review, or a strategic change:

    line 285
  30. Distinctive:

    update the source document that owns the decision

    line 287
  31. Very specific:

    update HANDOFF.md if implementation expectations changed

    line 290
  32. Very specific:

    Read references/integrations.md before use.

    line 295
  33. Very specific:

    If TYPESAFE_API_KEY or the integration is unavailable, fall back to ordinary reasoning.

    line 313
  34. Distinctive:

    Use Firecrawl only when the research problem benefits from deeper web extraction/crawling.

    line 317
  35. Distinctive:

    If Firecrawl is unavailable, use the environment's normal web/search tools and continue.

    line 327
  36. Distinctive:

    When Design Maestro is installed, invoke it for:

    line 331
  37. Very specific:

    After the Maestro phase finishes, Product Studio must translate stable results into the appropriate .design/ documents.

    line 340
  38. Distinctive:

    When sources disagree, use this order unless the user explicitly overrides it:

    line 346
  39. Distinctive:

    Do not silently let an old territory override a newer approved design direction.

    line 355
  40. Distinctive:

    avoid multiple agents editing the same source-of-truth file concurrently when possible

    line 365
  41. Very specific:

    Use HANDOFF.md as the implementation-facing contract and DECISIONS.md as the durable history of major choices.

    line 367
  42. Distinctive:

    Do not output this bookkeeping when it adds no value to a tiny task.

    line 380
  43. Distinctive:

    Read only what the current phase needs:

    line 384

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Product Studio

Operate as the persistent product/design system around a project. Maintain durable state, coordinate Design Maestro for creative direction, record important decisions, and keep research, brand, UX, content, QA, and implementation handoff aligned over time.

Product Studio is not a visual style and not a code generator. It is the project's design memory and operating model.

Core relationship

Use Product Studio for persistence and lifecycle management. Use Design Maestro for creative orchestration and design judgment. Use specialist skills for domain depth.

Product Studio (state + process)
        -> Design Maestro (creative direction)
                -> specialist skills
        -> Product Studio (record stable decisions)

If Design Maestro is unavailable, continue with the Product Studio workflow and apply the same product-first principles, but do not claim Design Maestro ran.

Non-negotiable rules

  1. Treat .design/ as the durable source of truth for product/design decisions when a working directory exists.
  2. Never replace approved decisions silently. Record meaningful changes in DECISIONS.md.
  3. Do not dump chat transcripts into the workspace. Persist conclusions, evidence, rationale, constraints, and open questions.
  4. Separate facts, assumptions, experiments, and approved decisions.
  5. Preserve provenance for external research so future agents can verify it.
  6. Keep product strategy, brand, UX, content, and implementation constraints connected.
  7. Code is downstream of product/design decisions unless the user is explicitly working in an implementation phase.
  8. JEV and Firecrawl are optional accelerators. Their absence must never block the workflow.
  9. JEV can inform routing and readiness; it cannot become the creative authority.
  10. Human/user decisions control irreversible or identity-level choices.
  11. Read existing .design/ state before proposing changes. Never assume a blank slate when project state exists.
  12. Prefer small, explicit updates to the workspace after each meaningful phase.

Workspace contract

When a working directory is available, use this project-local structure:

.design/
├── BRIEF.md
├── PRODUCT.md
├── RESEARCH.md
├── BRAND.md
├── DESIGN.md
├── EXPERIENCE.md
├── CONTENT.md
├── DECISIONS.md
├── QA.md
├── HANDOFF.md
├── territories/
├── references/
└── reviews/

Use scripts/init_design_workspace.py to create missing files without overwriting existing work.

Read references/design-state.md for ownership and update rules.

Startup procedure

If .design/ already exists

  1. Read BRIEF.md, PRODUCT.md, DESIGN.md, DECISIONS.md, and QA.md first.
  2. Read other files only as needed for the current task.
  3. Identify current phase, approved decisions, open questions, and stale assumptions.
  4. Continue from the existing state; do not restart discovery by default.

If .design/ does not exist

  1. Initialize the workspace.
  2. Seed BRIEF.md with known facts and assumptions.
  3. Create the smallest useful product frame.
  4. Continue into the appropriate workflow.

If no writable working directory exists

Run in conversational mode. Keep the same mental model and produce a proposed .design/ state as a handoff artifact if useful, but do not pretend files were persisted.

Lifecycle

Phase 0 - Orient

Resolve:

  • project identity
  • current artifact/state
  • current phase
  • target outcome
  • constraints
  • approved decisions
  • unresolved decisions

Update BRIEF.md only when the project frame materially changes.

Phase 1 - Product frame

Maintain in PRODUCT.md:

  • audience / user roles
  • primary jobs
  • business goal
  • product promise
  • primary success event
  • value/proof model
  • constraints and non-goals
  • product principles

Do not jump to visual styling when product logic is unresolved.

Phase 2 - Research

Use research only when it can change a product/design decision.

Maintain RESEARCH.md as a synthesis, not a bookmark dump:

  • question being investigated
  • sources and dates
  • findings
  • confidence / limitations
  • implications
  • decisions influenced

Use normal web/search first. Escalate to Firecrawl for deeper crawling, multi-page extraction, or structured research sets when it adds value.

If JEV is available, it may rerank/classify research fragments before synthesis. Preserve citations/provenance.

Phase 3 - Product story and content

Maintain CONTENT.md with:

  • core message hierarchy
  • terminology
  • primary claims
  • proof requirements
  • CTA language
  • content modules
  • voice constraints
  • unresolved copy questions

Content structure should support product comprehension before SEO optimization.

Phase 4 - Design territories

Use Design Maestro for creative exploration when available.

Store each serious territory as a file under territories/, for example:

territories/
├── 01-precision-infrastructure.md
├── 02-editorial-intelligence.md
└── 03-autonomous-motion.md

Each territory should define:

  • thesis
  • product story
  • composition / layout language
  • typography character
  • color logic
  • imagery/illustration
  • interaction/motion character
  • signature moment
  • differentiation
  • tradeoffs / risks
  • best-fit contexts

Do not treat palette swaps as separate territories.

Phase 5 - Decision checkpoint

For materially different territories or identity-level choices, keep the human/user in the decision loop.

When a choice is made, append to DECISIONS.md:

  • date
  • decision
  • status
  • rationale
  • evidence
  • alternatives considered
  • consequences
  • owner if relevant

Do not hide a creative choice behind a JEV score.

Phase 6 - Brand and visual system

Maintain BRAND.md and DESIGN.md.

BRAND.md owns:

  • positioning-relevant personality
  • visual metaphor
  • identity principles
  • logo/mark rules when applicable
  • typography direction
  • palette intent
  • imagery direction
  • voice/tone relationship
  • forbidden/avoid patterns

DESIGN.md owns:

  • grid/container logic
  • hierarchy
  • spacing rhythm
  • semantic color roles
  • typography roles
  • surfaces/depth
  • shape/radius rules
  • iconography
  • motion principles
  • signature moments
  • responsive design principles

Document intent and roles, not only raw pixels.

Phase 7 - Experience model

Maintain EXPERIENCE.md with:

  • sitemap/screen map
  • navigation model
  • key flows
  • state model
  • primary/secondary actions
  • feedback
  • empty/loading/error/success states
  • keyboard/touch/pointer behavior
  • responsive transformations
  • accessibility requirements

Use specialist skills for interaction, adaptation, Apple-platform guidance, or accessibility as needed.

Phase 8 - Reviews and gates

Store substantial review outputs in reviews/ and keep QA.md as the current summary.

Recommended gate families:

  • Discovery ready: enough context to explore product/design directions.
  • Direction ready: enough evidence and product clarity to choose a territory.
  • Build ready: hierarchy, content, system, states, responsive behavior, and accessibility requirements are sufficiently specified.
  • Ship ready: implementation has passed the relevant design/accessibility/content checks.

JEV may evaluate atomic gate criteria if available. Record the rubric and evidence. Do not use one vague "quality score".

Read references/gates.md.

Phase 9 - Handoff

Maintain HANDOFF.md as the current implementation contract.

It should include:

  • goal and audience
  • approved direction
  • page/screen map
  • content hierarchy
  • design-system decisions
  • interaction states
  • responsive rules
  • accessibility requirements
  • SEO/AI-discovery requirements when relevant
  • assets/references
  • things not to change
  • open questions
  • implementation constraints
  • recommended specialist skills for the next phase

Handoff is a decision document, not a transcript.

Phase 10 - Maintain

After implementation feedback, user testing, review, or a strategic change:

  1. update the source document that owns the decision
  2. append major changes to DECISIONS.md
  3. refresh QA.md
  4. update HANDOFF.md if implementation expectations changed
  5. mark obsolete territory/review docs as superseded rather than deleting useful history without reason

Optional JEV layer

Read references/integrations.md before use.

Appropriate JEV roles:

  • classify incoming intent
  • suggest relevant specialist skills from the live catalog
  • rerank research fragments
  • classify review findings
  • evaluate atomic readiness criteria

JEV must not:

  • invent the product strategy
  • choose the brand identity as an unquestioned authority
  • generate the final design direction
  • replace evidence or user research
  • replace accessibility verification

If TYPESAFE_API_KEY or the integration is unavailable, fall back to ordinary reasoning.

Optional Firecrawl layer

Use Firecrawl only when the research problem benefits from deeper web extraction/crawling.

Examples:

  • competitor homepage + product-page comparison
  • multi-page content inventory
  • structured category research
  • extracting dynamic websites
  • discovering a site's information architecture

If Firecrawl is unavailable, use the environment's normal web/search tools and continue.

Design Maestro integration

When Design Maestro is installed, invoke it for:

  • product/design direction
  • design territories
  • specialist routing
  • visual-system synthesis
  • critique/review orchestration
  • implementation handoff synthesis

After the Maestro phase finishes, Product Studio must translate stable results into the appropriate .design/ documents.

Product Studio owns persistence; Design Maestro owns creative orchestration.

State precedence

When sources disagree, use this order unless the user explicitly overrides it:

  1. latest explicit user decision
  2. latest approved entry in DECISIONS.md
  3. current owning document (PRODUCT.md, BRAND.md, DESIGN.md, etc.)
  4. verified external evidence
  5. specialist recommendation
  6. old exploration/review material

Do not silently let an old territory override a newer approved design direction.

Multi-agent behavior

For work distributed across agents:

  • give each agent the smallest relevant .design/ subset
  • tell the agent which files are authoritative
  • require returned findings to distinguish facts, proposals, and decisions
  • merge stable outcomes back into the owning documents
  • avoid multiple agents editing the same source-of-truth file concurrently when possible

Use HANDOFF.md as the implementation-facing contract and DECISIONS.md as the durable history of major choices.

Output behavior

For each substantial session, finish with a compact state summary:

  • what changed
  • which .design/ files were updated
  • decisions made
  • decisions still open
  • current gate/status
  • recommended next phase

Do not output this bookkeeping when it adds no value to a tiny task.

References

Read only what the current phase needs:

  • references/operating-model.md - architecture and Product Studio vs Design Maestro.
  • references/design-state.md - .design/ file ownership and state rules.
  • references/workflows.md - end-to-end workflows for websites, apps, redesigns, and reviews.
  • references/gates.md - readiness and quality gate patterns.
  • references/integrations.md - JEV/TypeSafe AI and Firecrawl optional integration rules.
  • references/handoff.md - handoff contract and multi-agent patterns.
  • references/examples.md - concrete usage examples.

Scripts

  • scripts/init_design_workspace.py - create missing .design/ structure without overwriting existing state.
  • scripts/check_design_workspace.py - report required files, empty files, and current workspace completeness.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.