Vision skill
A skill that drafts VISION.md from your PR and commit history, stress-tests it with hard questions and refines it with you on an interactive board
- 332 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The skill reads repository history and PR text through `gh` or `gh-axi`, which means it calls GitHub on your behalf
- The board starts with `npx -y lavish-axi`: the package is downloaded from npm and runs on your computer
- The agent creates or edits `VISION.md` in the repository
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/vision-skillDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill reads repository history and PR text through `gh` or `gh-axi`, which means it calls GitHub on your behalf
- The board starts with `npx -y lavish-axi`: the package is downloaded from npm and runs on your computer
- The agent creates or edits `VISION.md` in the repository
This is third-party code. Review the repository files before installing.
What it does
The `vision` skill drafts a `VISION.md` file for a repository: a testable policy of what the project accepts and what it refuses. It starts with `/vision` inside the repository or `/vision owner/repo`, and also when asked to write or refine a project vision. First the agent studies the evidence: it reads the project description, architecture and stated non-goals, then takes 30 to 100 titles of the author's merged PRs and reads the full text of 8 to 15 of them. If PRs are not accessible, it walks the commit history of the default branch. This produces a private evidence sheet: every line of the draft must rest on real PRs, commits or files. From the sheet the agent writes a draft of 40 to 70 lines: the project's purpose, 3 to 6 principle sections, non-goals and two closing tests, when a change aligns and when it should be resisted. Then it designs 8 to 12 hypothetical proposals on contested boundaries where both yes and no are defensible, for example a tempting off-mission feature or expansion to new users. If the author's answer is predictable, the question is replaced. The questions are assembled into a board from the `review-template.html` template and the `review.css` styles: the full draft stays visible on the left, cards are dealt one at a time on the right. The board is launched with `npx -y lavish-axi`. The agent weaves each answer into the text of `VISION.md` and notes it in a changelog. If `VISION.md` already exists, the skill works in delta mode and proposes only separate edits based on newer evidence.
Who it is for. For authors and maintainers of open projects who need a written criterion by which they, contributors and agents accept or reject changes.
Good fit when
- Proposals keep arriving and each time you re-explain why you accept some features and decline others
- You need a `VISION.md` you can point to when declining a PR
- An old `VISION.md` is out of date and needs what the project has done recently
- Coding agents work in the repository and need a short document on what the project must not turn into
- You want to test your own vision on contested examples before publishing it
Not a fit when
- The project has no readable PR or commit history: the skill stops and will not invent your values
- You need a roadmap, a feature list or a marketing description: the skill's rules forbid such sections in `VISION.md`
- You are not ready to answer hard questions: only the author can give verdicts on the cards, and the skill does not treat silence as consent
- The environment cannot run `npx` and open a page in a browser, and the board does not work without that
- You need a product description for users: `VISION.md` is written for a reviewer who decides whether to accept a change
Example request
Help me write a VISION.md for this repository from my merged PRs and test it on contested proposalsLimitations
- The skill needs access to the repository and its history: merged PRs through `gh` or `gh-axi`, and without them the commit log of the default branch.
- The board launches through `npx -y lavish-axi` with no separate install, so the package is downloaded from npm on first run. If the launch fails, the skill reports a blocker.
- The result depends on the quality of the history: by the skill's rule every principle must rest on specific PRs or commits, and with a thin history the document comes out short.
- The skill does not approve the document for the author. Approval, answers to the cards and the decision to commit stay with you.
- The repository is small: it holds `SKILL.md`, the board template and styles, with no tests or run examples. The author shows a sample result through a link to the `VISION.md` of another of his projects. MIT license.
How to disable. Delete the `vision` folder from the agent's skills folder: for a global install through `npx skills add -g` that is the skills folder in your home directory. The `VISION.md` created in the repository stays, and you can delete it like any file.
FAQ
What is VISION.md and how does it differ from a README?
By the skill's formula it is a policy for accepting changes: what the project exists for, its 3 to 6 principles, what it is not, and when a change aligns or should be resisted. A reviewer who never saw the board must be able to accept or reject a PR from this file alone. It must hold no roadmap, feature list or marketing.
Where does the skill get the project's values?
From your merged PRs: 30 to 100 titles and 8 to 15 full texts. It extracts what recurs, for example what you build, what you refuse and which bugs you fix at the root. If PRs are not accessible, the skill reads the commit log of the default branch. Generic virtues such as we value quality are banned unless the history demonstrates them.
What are the hypothetical questions on the board?
There are 8 to 12 per vision. They are concrete change proposals on the edge of the principles: tempting off-mission features, collisions such as simplicity against capability, slippery slopes and expansion to new users. For each the skill sets out both sides, and you give a verdict that ends up in the text of the document.
What happens if VISION.md already exists?
The skill switches to delta mode. The existing file on the default branch counts as the approved baseline, and the skill proposes line-level edits based on newer evidence, each acceptable on its own. It does not create a competing document.
Where do the answers from the board go?
Only into the text of `VISION.md`: the reasoning is woven into the prose, while the questions, card ids and board transcripts are not committed to the repository. If an old `VISION-ANSWERS.md` sits nearby, the skill folds its content into `VISION.md`, deletes the file and removes pointers to it.
How is the finished document formatted?
One sentence per line, present tense, plain hyphens instead of em dashes and a length of a page or two. The sample structure is an opener on why the project exists, principle sections, a section on what the project is not, and two closing tests for alignment and resistance.
Discussion
No questions or reviews yet.
Related
SkillsSkill that adapts a research manuscript to a journal: it builds writing rules from published papers and revises a manuscript by section with a log
The paper-spine skill takes a topic, materials and data through a scientific paper: literature, text, figures, review and Word, LaTeX and PDF files
Learn from materials
learn-from-materials
A skill that turns books, PDFs, slides and documents into a traceable knowledge base and an interactive learning page with sources, maps and self-check
Takes an agent from a topic to an arXiv review paper in LaTeX IEEEtran: approved plan, every citation checked against a live source, PDF build
A skill that typesets resumes, one-pagers, letters, reports and slides from templates into PDF, PNG and PPTX and checks the result before delivery
A skill that turns an article, report or notes into a deck of full-slide images and assembles them into a pptx
README in short
The description opens with a question about what the project refuses to become and four points on evidence from history, testing on hard hypotheticals, the board's design and a single document instead of transcripts. Then come a two-command quick start, access requirements, a seven-step diagram, a table of ways to invoke the skill, the package structure and commands for local checks. A link to the `VISION.md` of the firstmate project serves as a sample of the result.
README badge
Original SKILL.md
---
name: vision
description: >
Draft and stress-test a VISION.md for a repository, then iterate with the
author on an interactive review board until approved. Use on /vision or when
asked to create or refine a project vision.
user-invocable: true
metadata:
short-description: "Evidence-mined, stress-tested VISION.md for any repo"
---
# /vision
You are running the **vision** skill. Produce a VISION.md the author can
approve: an acceptance policy for the project's future, grounded in what they
actually build, and sharpened by hypotheticals they answer on an interactive
review board.
VISION.md is the only committed alignment surface. A reviewer who has never
seen the board must be able to accept or resist a change from it alone.
This is not a writing exercise. Follow this file top to bottom.
## Host requirement
You need read access to the target repository and its real history:
- Prefer merged-PR history via a GitHub-class CLI (gh, gh-axi).
- If PRs are not accessible, fall back to git commit history on the default
branch (git log): titles and messages still reveal what the author builds.
- Only if no real history is readable at all, **stop** and say so. Never
fabricate the author's values, PR titles, or evidence. A vision built on
invented evidence is worse than no vision.
The review loop runs on lavish-axi, executed directly through
`npx -y lavish-axi` - no install requirement. Simply try to launch it, and
report a blocker only if the launch itself fails.
## Hard rules
1. **Evidence over vibes.** Every principle in the draft must be traceable to
concrete evidence: named PRs or commits, files, docs, or reasoning the
author approved into VISION.md. Generic engineering virtues ("we value
quality") are banned unless the history demonstrates them specifically.
2. **Check for an existing VISION.md first.** If one exists on the default