How the OKR Planning Skill Facilitates Objective and Key Results Definition

The OKR planning skill (brainstorm-okrs) in the phuryn/pm-skills repository guides product teams through a six-step structured workflow to generate aligned, measurable OKRs by processing strategic context and applying the Objective and Key Results framework.

This Claude plugin skill automates the complete lifecycle of OKR creation within the phuryn/pm-skills open-source project. By combining structured prompting with document ingestion capabilities, it transforms raw strategic inputs into concrete, quarterly-ready objective and key results definitions.

What Is the OKR Planning Skill?

The OKR planning skill is defined in pm-execution/skills/brainstorm-okrs/SKILL.md and exposed to users through the /plan-okrs command defined in pm-execution/commands/plan-okrs.md. Unlike generic planning templates, this skill implements a reasoning-based approach that forces the model to analyze company strategy before generating outputs.

The skill is registered within the .claude-plugin/plugin.json configuration, making it available as a reusable component across Claude-compatible clients. It specifically targets product teams needing to ladder team-level objectives up to broader company goals while maintaining strict measurability standards.

The Six-Step OKR Definition Workflow

The skill implements a rigorous six-phase process that ensures every generated OKR is strategically grounded and quantifiable.

1. Strategic Context Gathering

First, the skill reads uploaded company objectives, strategy documents, or team briefings. If users reference external strategy without providing documents, the skill can trigger web searches to supplement its knowledge base. This phase ensures all subsequent OKR definitions align with actual business priorities rather than generic templates.

Implementation reference: brainstorm-okrs SKILL.md – "Gather Context" section (lines 31-33).

2. Framework Understanding

Before generating content, the skill internalizes the distinction between Objectives (qualitative, inspirational, time-bound statements) and Key Results (quantitative, measurable outcomes). It also clarifies the relationship between OKRs, KPIs, and the North Star Metric to prevent common definition errors.

Implementation reference: brainstorm-okrs SKILL.md – "Understand the Framework" (lines 33-36).

3. Step-by-Step Reasoning

The skill prompts the model to think through four critical dimensions before writing any OKRs:

• Current company strategy and priorities
• High-impact areas requiring focus
• Alignment points with cross-functional teams
• Success criteria for both customers and the business

This reasoning phase prevents superficial goal-setting by forcing explicit connections between strategy and execution.

Implementation reference: brainstorm-okrs SKILL.md – "Think Step by Step" (lines 37-42).

4. Three-Set Generation

Rather than producing a single option, the skill generates three distinct OKR sets. Each set contains exactly one concise Objective and three measurable Key Results that ladder directly to company goals. This approach gives teams alternatives while maintaining consistency in format and rigor.

Implementation reference: brainstorm-okrs SKILL.md – "Generate Three OKR Sets" (lines 43-48).

5. Structured Formatting and Persistence

The skill returns results in standardized markdown format and optionally persists them as OKRs-[team-name]-[quarter].md. This automated file naming convention ensures version control and discoverability across product cycles.

Implementation reference: brainstorm-okrs SKILL.md – "Structure Output" and "Save the Output" (lines 50-66).

6. Further Learning Resources

Finally, the skill appends curated links to external OKR methodology resources, enabling teams to deepen their understanding of the framework beyond the immediate planning session.

Implementation reference: brainstorm-okrs SKILL.md – "Further Reading" (lines 75-81).

How to Invoke the OKR Planning Skill

Users interact with the skill through the /plan-okrs command. The command parser handles argument extraction and document ingestion before handing control to the underlying skill.

# Example CLI-style invocation

>>> /plan-okrs "Team: Mobile Growth" "Upload: company_strategy.pdf"

The skill returns three ready-to-use OKR drafts following this structure:

Objective: Accelerate mobile-first user acquisition
Key Results:
- Increase MAU growth rate from 4% → 7% MoM
- Reduce cost-per-install (CPI) from $1.80 → $1.30
- Boost activation rate from 45% → 60% within 7 days

For programmatic integration, the skill can be embedded via the Claude SDK:

from claude_plugin import ClaudeClient

client = ClaudeClient()
response = client.run_command(
    command="/plan-okrs",
    args={"team": "Mobile Growth"},
    files={"company_strategy.pdf": open("company_strategy.pdf", "rb")}
)

print(response.text)   # contains the three OKR sets

Key Implementation Files

File	Role	Location
SKILL.md	Core skill definition containing the six-step logic, framework rules, and output specifications.	pm-execution/skills/brainstorm-okrs/SKILL.md
plan-okrs.md	Command wrapper that exposes the skill to end users and handles argument parsing.	pm-execution/commands/plan-okrs.md
plugin.json	Plugin registration file that loads the skill set into the Claude platform.	pm-execution/.claude-plugin/plugin.json
README.md	Repository documentation listing the skill among 16 execution capabilities.	Repository root

Summary

• The OKR planning skill (brainstorm-okrs) provides a structured, six-step workflow for defining objectives and key results in the phuryn/pm-skills repository.
• It ensures strategic alignment by requiring context gathering and explicit reasoning before generation.
• The skill outputs three complete OKR sets, each containing one Objective and three measurable Key Results.
• Implementation resides in pm-execution/skills/brainstorm-okrs/SKILL.md and is invoked via the /plan-okrs command.
• Automated formatting and file persistence standardize OKR documentation across teams.

Frequently Asked Questions

How does the OKR planning skill ensure strategic alignment?

The skill requires explicit context gathering from company strategy documents and web searches before generating any OKRs. During the "Think Step by Step" phase, it forces the model to identify alignment points with company priorities and cross-functional dependencies, ensuring all outputs ladder up to organizational goals rather than existing in isolation.

What is the exact output format of the OKR planning skill?

The skill generates three distinct markdown-formatted OKR sets. Each set contains exactly one qualitative Objective (inspirational and time-bound) followed by three quantitative Key Results with specific metrics and target values. The output optionally saves to a file named OKRs-[team-name]-[quarter].md for version control.

Can the OKR planning skill process external strategy documents?

Yes. The skill accepts uploaded PDFs, text files, or other strategy documents during the initial context gathering phase. If references are made to external strategies without attachments, the skill can trigger web searches to supplement its knowledge base before proceeding with OKR definition.

What distinguishes this skill from standard OKR templates?

Unlike static templates, the brainstorm-okrs skill implements dynamic reasoning chains that adapt to specific company contexts. It generates three alternative OKR sets rather than one, enforces strict measurability requirements (exactly three Key Results per Objective), and explicitly links outputs to the North Star Metric and KPI framework defined in the source code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}