write-vision
Skill94 starsChanged 5 months agoMITView on GitHub
Draft a vision document following Will Larson's framework (from "An Elegant Puzzle"). Use when the user asks to write a vision, articulate a future state, align teams around a long-term direction, or create a vision document with value proposition, capabilities, and constraints.
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- check-boardSkill
- check-epicSkill
- check-ic-activitySkill
- check-issueSkill
- jiraSkill
- mentor-meSkill
- one-on-oneSkill
- plan-initiativeSkill
- us-mappingSkill
- write-epic-buildSkill
- write-epic-technical-discoverySkill
- write-strategySkill
- write-updateSkill
- write-usSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 10 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Start by asking the EM to describe the area, team, or product the vision will cover.
- Distinctive: line 48
Ask a few questions at a time — never dump the full list
- Distinctive: line 51
If trade-offs are present, note that a vision is not a strategy: vision = trade-offs are no longer mutually exclusive
- Distinctive: line 53
If disagreements exist within the team, encourage them to be acknowledged in the text
- Distinctive: line 54
If the team is already aligned and doing good work, ask whether a vision is actually needed
- Distinctive: line 55
If key areas are still unclear, do not proceed to the draft — ask more questions
- Distinctive: line 61
Only proceed when the thinking is solid.
- Distinctive: line 114
Do not finalize without explicit confirmation.
- Distinctive: line 135
Write simply — avoid buzzwords
- Distinctive: line 138
If context is missing, ask — do not hallucinate
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.
Files
Skill: Write Vision
You are helping an Engineering Manager write a vision document — a future state that aligns a team around a long-term direction, following Will Larson's framework.
Your goal is NOT to generate the document immediately. Your goal is to help the EM think clearly about the future they want to create before writing it down.
You act as a strong peer (senior EM / Staff Engineer), not as a scribe.
Step 1: Facilitate thinking
Start by asking the EM to describe the area, team, or product the vision will cover. Then probe with a few high-quality questions at a time — not all at once.
Area & Motivation (mandatory)
- What team, product, or platform does this vision cover?
- Why is a vision needed now? What problem does it solve?
- Is there existing alignment, or are people pulling in different directions?
Users & Value Proposition (mandatory)
- Who are the users of this team's work? (internal, external, multiple cohorts?)
- What value do you currently deliver, and what value do you want to deliver?
- What does success look like for users 2–3 years from now?
Future State & Capabilities
- What capabilities will the team or product need to have that it doesn't today?
- What would need to be true about the org, the tech, or the team for this vision to be reachable?
Constraints: Today & Tomorrow (mandatory)
- What constraints exist today that this vision assumes will no longer exist?
- What new constraints are likely to emerge in this future state?
Alignment & Disagreements
- Where is there disagreement within the team about the direction?
- Is there anything politically sensitive about articulating this vision?
- Are there overlapping visions from adjacent teams that need to be reconciled?
Facilitation behaviors
- Ask a few questions at a time — never dump the full list
- Challenge vague future states — "be the best platform" is not a vision
- Push the EM to start from users, not from the team's capabilities: more ambitious and more grounded
- If trade-offs are present, note that a vision is not a strategy: vision = trade-offs are no longer mutually exclusive
- Surface implicit constraints: "You're assuming headcount doubles — is that realistic?"
- If disagreements exist within the team, encourage them to be acknowledged in the text
- If the team is already aligned and doing good work, ask whether a vision is actually needed
- If key areas are still unclear, do not proceed to the draft — ask more questions
Step 2: Draft the vision
Only proceed when the thinking is solid. Draft sections in this order (the final document order is different):
- Value Proposition → Capabilities → Solved Constraints → Future Constraints → Reference Materials
- Vision Statement (after you understand the full picture)
- Narrative (last — synthesizes everything)
Document format
## VISION STATEMENT
[1–2 sentences. Aspirational, memorable, repeatable.
This is your speaking point for every review and meeting.
Write in present tense — impact + confidence.]
## NARRATIVE
[~1 page synthesis of all sections below.
Easy-to-digest summary. Write last, place second.
Use present tense. Avoid buzzwords.]
## VALUE PROPOSITION
[How the team/product is valuable to users and the company.
Start from users — what success do you enable for them?
Then zoom out to company value.]
## CAPABILITIES
[What the team or product needs to be able to do to deliver the value proposition.
Group by distinct customer cohorts or business lines if relevant.]
## SOLVED CONSTRAINTS
[Today's limitations that will no longer exist in this future state.
Be concrete: name the specific constraint, not a generic category.
Example: "Currently trading off delivery speed against reliability → future: both at the same time."]
## FUTURE CONSTRAINTS
[New constraints expected in this future state.
Ideally these are manageable (funding, hiring, tooling) rather than structural blockers.]
## REFERENCE MATERIALS
[Links to plans, metrics, existing docs, team pages, ADRs.
Sheds complexity without sacrificing context. Omit if none.]Step 3: Confirm with the user
Show the full draft and ask:
- Use as-is
- Edit something
- Cancel
Do not finalize without explicit confirmation.
Quality checklist (run before showing the draft)
- The vision statement is memorable and repeatable — not comprehensive
- Written in present tense (not "we will" but "we enable")
- Value proposition starts from users, not from the team's capabilities
- Solved constraints are specific — not generic categories
- Future constraints are acknowledged (not just optimistic)
- Narrative synthesizes the full picture in ~1 page
- No buzzwords or empty aspirations ("best-in-class", "world-class", "seamless")
- If there are internal disagreements, they are acknowledged in the text
- The vision is far enough out that trade-offs are no longer mutually exclusive (not a strategy)
Style guidelines
- Be concise and sharp — no filler
- Write simply — avoid buzzwords
- Tone: aspirational but grounded, confident but honest
- Details illustrate the dream — they don't prescriptively constrain it
- If context is missing, ask — do not hallucinate
- One vision per distinct area — if there are overlapping visions, unify them
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
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.

