define-north-star

Skill: Define North Star

Purpose

DefinitionNorth Star Metric (NSM): The single most important metric that captures the core value delivered to users. Use the NSM to generate a document explaining why it represents user value, optional supporting metrics (3-5), and anti-North Star examples. Do not define mission, vision, strategic goals, or milestones.

Core Objective

Primary Objective: Generate a user-confirmed North Star document containing one primary metric that reflects user value and behavior influenced by the product, and adhere to the project's agreed path.

Success Criteria(all requirements must be met):

✅ North Star Metric Definition: One primary metric with a clear, measurable definition (name + measurement method).
✅ Rationale Record: Explain why this metric represents user value (not vanity or revenue only).
✅ Principles Met: The NSM reflects user value, represents user behavior, measures sustained engagement, is product-driven, and is simple and clear.
✅ User Confirmation: Explicit user approval (e.g., "approved", "looks good", "continue", or equivalent).
✅ Document Persistence: Write to the agreed path (default docs/project-overview/north-star.md or per project specification).
✅ Anti-patterns Listed: List at least 2-3 vanity or anti-North Star metrics as examples of what should not be optimized (e.g., revenue, total users, sign-ups, downloads, raw page views).

AcceptanceTest: Can a reader understand within one minute which single metric defines the product's success and why it reflects user value rather than vanity?

Handoff Point: When the "North Star" is approved and adhered to, hand it off to "Design-Strategy-Goals" to set goals that drive the NSM, or stop.

Scope Boundaries

This skill is responsible for：

Deriving one primary North Star metric from user value and product context.
Documenting why this metric represents user value (not vanity).
Optional: 3-5 supporting metrics that complement the NSM.
Listing anti-North Star metrics (vanity examples) that should not be used as the North Star.
Adhering to the project-agreed path (default "docs/project-overview/north-star.md").

This skill is not responsible for：

Defining mission or vision (use "Define Mission", "Define Vision").
Defining strategic goals or OKRs (use "Design Strategic Goals").
Defining milestones (use "Define Milestones").
Writing roadmaps, requirements, or backlogs (use project planning, "Analyze Requirements", "Capture Work Items").

Usage Scenarios (Use Cases)

After Vision: Once the vision is clear, establish the metric that best captures "delivered value".
Product Prioritization: When the team needs a single metric to guide what to optimize.
Replacing Vanity Metrics: When the current focus is revenue, total users, downloads, or page views and the team wants a user-value anchor.
Third Layer in the Strategy Chain: Follow the mission and vision when building the complete hierarchy.

Behavior (Behavior)

Interaction Strategy

Follow Defaults first, Prefer choices, Context inference:

Default: Load the mission/vision from docs/project-overview/ or the project specification; the output path is taken from the project specification or docs/project-overview/north-star.md. When there is no additional input, run the derivation framework directly.
Choose options: When multiple candidate metrics exist, provide 1–3 and explain the rationale, letting the user choose or refine.
Confirm: User approval must be obtained before overwriting an existing north-star file and before persisting. If a candidate is a vanity metric, warn and suggest a behavior-based alternative.

North Star Principles (apply when deriving metrics)

Reflect user value, not just company revenue.
Represent user behavior, not vanity statistics.
Measure sustained engagement, not one-time events.
Be product-driven: the product team can influence it.
Simple and clear: ideally a single measurable metric.

Derivation Framework (execution flow)

Use this reasoning chain to derive the North Star:

User
  ↓
Core Value Delivered
  ↓
Primary User Action
  ↓
Observable Behavior
  ↓
Measurable Metric (North Star)

Context: Load the mission/vision from docs/project-overview/ or the user; determine the target users and core value proposition.
Core value: What value does the product bring to users? (Not "revenue"—user outcomes.)
Primary action: What is the primary user action that reflects this value?
Observable behavior: What behaviors can we observe (e.g., messages sent, nights booked, time spent)?
Metric: Define a measurable metric to capture that behavior; keep it simple.
Validation: Check against the five principles; avoid vanity (revenue, total users, sign-ups, downloads, raw page views as the North Star).
Measurement and limitations(optional): If the metric depends on external data sources or cannot currently be measured directly, add a "Measurement and limitations" section to the output document, explaining the dependencies and alternative strategies.
Supporting metrics(optional): Add 3–5 metrics that support or complement the NSM.
Counterexamples: List 2–3 metrics that should not be used as the North Star, with brief reasons.
Persist: Write to the agreed path; create the directory if it does not exist.

Anti-patterns (not recommended as the North Star)

Revenue (a company outcome, not user value).
Total users (vanity; does not reflect engagement or value).
Sign-ups (one-time; not sustained engagement).
Downloads (one-time; not behavior).
Raw page views (vanity; not a value-delivery behavior).

These may appear only asanti-North-Star examplesin the output, not as the selected metric.

Input & Output (Input & Output)

Input：

Required: Project/product description; target users; core value proposition (or mission/vision path).
Optional: Mission/vision text or path; current metrics; constraints; examples of similar products.

Output：

Artifact: North Star document.
Path：docs/project-overview/north-star.md(or project specification).
Structure: Metric definition, derivation chain, principles, optional supporting metrics, optional measurement and limitations, anti-North Star examples. Keep it concise (YAGNI, DRY).
Lifecycle: living (updated when the product or strategy changes).

Constraints (Limitations)

Hard Boundaries

Do not define the mission, vision, strategic goals, or milestones in this skill.
Do not propose vanity metrics (revenue, total users, sign-ups, downloads, raw page views) as the North Star; list them only as counterexamples.
Do not overwrite an existing North Star file without explicit user confirmation.

When to Stop (Handoff)

User says "approved" or equivalent → North Star complete; hand off to design-strategic-goals。
User asks about goals or milestones → hand off to design-strategic-goals or define-roadmap。

Skill Boundaries (Avoid Overlap)

Do not do these (other skills can handle them)：

Mission: why it exists → use define-mission
Vision: what future to build → use define-vision
Strategic goals: 3–5 outcomes → use design-strategic-goals
Milestones: phase checkpoints → use define-roadmap

Self-Check

Core Success Criteria (all criteria must be met)

North Star metric definition: one primary metric with a clear, measurable definition.
Rationale recorded: why this metric represents user value (rather than vanity).
Principles satisfied: user value, behavior, sustained engagement, product-driven, simple.
User confirmation: user says "approved," "looks good," "continue," or similar.
Document persistence: write to the agreed path (default docs/project-overview/north-star.md or project specification).
Antipatterns listed: at least 2-3 vanity/anti-North Star examples in the document.

Process Quality Checks

Derivation used: was the user → core value → action → behavior → metric chain applied?
Measurement and limitations: if the metric depends on external data or is currently unobservable, was a "Measurement and Limitations" section added?
No vanity NSM: is revenue, total users, sign-ups, downloads, or raw page views avoided as the North Star?

Acceptance Test

Can a reader understand within one minute which single metric defines success and why it reflects user value?

If no: the NSM is unclear or vanity. Re-derive using the framework and principles. If yes: the North Star is complete. Proceed to handoff or stop.

Examples

Example 1: From Vision to North Star

Background: The vision is "every team can deliver to production in 5 minutes with a single click." Target users: engineering teams. Core value: reliable, fast deployment.

Process: Core value = successful, low-friction deployment. Primary action = complete a deployment. Observable behavior = number of successful deployments within the time/simplicity bar. Metric: "successful deployments per week (completed within 5 minutes of trigger)." Supporting: deployment frequency, rollback rate, deployment time. Counterexamples: total users, revenue, page views. User confirmation. Write to "docs/project-overview/north-star.md".

Result: The North Star persists; hand off to "Design Strategic Goals".

Example 2: User Suggests a Vanity Metric

Context: The user says "our North Star should be total registered users."

Process: Apply the principle—total users is vanity, not sustained engagement or behavior. Use the derivation: user → core value (e.g., "user completes X things") → primary action → observable behavior → metric. Propose a behavior-based alternative (e.g., "weekly active users who complete at least one core action") and list "total registered users" as a counter-North-Star example. Ask the user to confirm the behavior-based NSM or refine it.

Result: The document includes the chosen NSM and the counterexample "total registered users - not sustained engagement"; persistence complete.

Example 3: The Metric Has Measurement Limitations

Background: The NSM is "monthly skill adoption", but it depends on the API of an external ecosystem (such as skills.sh) being open, which currently cannot be accessed directly.

Process: After deriving the NSM, verify that all principles are satisfied. Add a "Measurement and Limitations" section explaining the dependency on vercel-labs/skills#426 or similar capability being implemented; until then it cannot be measured directly. Optionally add a statistics strategy for an organization's self-built registry (such as SkillReg, SkillHub). Persist after user confirmation.

Result: The document contains the NSM, derivation, principles, measurement and limitations, and counterexamples; readers know the metric is correctly defined but currently unobservable.