oneafrikanoneafrikan/the-grid/skills/openspec-help/SKILL.md

openspec-help

Skill4 starsChanged 8 days agoMITView on GitHub

Quick-reference card for OpenSpec in the-grid (the 12 wired skills, spec format, CLI). Use when the user asks "how do I use openspec", "how do I add specs to this repo", "what are the openspec commands" or "which openspec skill do I want".

In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cavemanSkill
- gh-issues-by-severitySkill
- grid-helpSkill
- grill-meSkill
- growth-psychSkill
- handoffSkill
- mine-learningsSkill
- rubber-duckSkill
- setup-repo-skillsSkill
- skill-scoutSkill
- spec-scoutSkill
- standupSkill
- tightenSkill
- un-claudishSkill

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
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:
Read a section only when its condition applies.
line 81

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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

openspec-help

One-shot reference. Not a mode — display and stop.

OpenSpec is spec-driven development: proposals get written and reviewed before code exists, and the spec survives the session that produced it. Upstream is Fission-AI/openspec (MIT), tracked at repos/openspec.

The 12 skills

Normal path — start here:

Skill	When
`/openspec-explore`	Thinking out loud before committing to a direction. No artefacts written.
`/openspec-propose`	You know what you want. Creates the change + all artefacts in one pass.
`/openspec-apply-change`	Proposal reviewed and accepted — implement the tasks.
`/openspec-verify-change`	Check the implementation actually matches the spec, before archiving.
`/openspec-archive-change`	Fold the delta into `openspec/specs/`, move the change to `archive/`.

When the normal path doesn't fit:

Skill	When
`/openspec-new-change`	Step-by-step artefact creation instead of `propose`'s one-shot.
`/openspec-continue-change`	Pick up a change someone (or a past session) left half-built.
`/openspec-ff-change`	Fast-forward — generate every artefact without stepping through.
`/openspec-update-change`	Revise an existing plan and keep its artefacts coherent. Never edits code.
`/openspec-sync-specs`	Push a delta into main specs without archiving the change.
`/openspec-bulk-archive-change`	Several parallel changes finished at once.
`/openspec-onboard`	Guided first cycle, narrated, on real work in your codebase.

Related, and not an openspec skill: /spec-scout audits adoption and reports spec↔code drift. Survey-only — it never writes specs.

Layout

openspec/
  specs/<capability>/spec.md     current truth — what the system does today
  changes/<change-id>/
    proposal.md                  what & why
    design.md                    how
    tasks.md                     implementation checklist
    specs/<capability>/spec.md   the DELTA — how the spec changes
  archive/                       completed changes

The distinction that matters: openspec/specs/ is present tense. openspec/changes/*/specs/ is a diff against it. Never hand-edit current truth as part of a change — write the delta, let archive or sync fold it in. That's the failure mode the whole convention exists to prevent.

Spec format

Plain markdown. No custom syntax.

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes, defaulting to
the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Headers are ADDED, MODIFIED, or REMOVED. Requirements use SHALL. Every requirement needs at least one WHEN/THEN scenario — one without is untestable and shouldn't merge.

Sections

Read a section only when its condition applies; do not preload them.

sections/adopting.md: read when asked how to adopt OpenSpec in a repo (init, greenfield, brownfield)
sections/the-grid-specifics.md: read when asked how OpenSpec is wired here, its CLI dependency, stores, or gotchas

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.

Check your setup, free