openspec-learning
Skill10 starsChanged 6 months agoMITView on GitHub
Capture one verified, non-obvious, reusable lesson from completed OpenSpec work in the project configuration so future OpenSpec workflows receive it. Use when the user invokes this skill, asks to preserve what was learned, says "openspec learning", or wants a solved problem turned into durable OpenSpec guidance.
In this repository24 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- openspec-apply-changeSkill
- openspec-archive-changeSkill
- openspec-exploreSkill
- openspec-proposeSkill
- openspec-sync-specsSkill
- openspec-update-changeSkill
- event-driven-analysisSkill
- fundamental-analysisSkill
- investment-notesSkill
- macro-analysisSkill
- market-data-lookupSkill
- market-info-recordingSkill
- portfolio-managementSkill
- report-consultingSkill
- risk-assessmentSkill
- sentiment-analysisSkill
- stock-analysisSkill
- task-managementSkill
- technical-analysisSkill
- transaction-managementSkill
- valuation-modelsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
24 rules. About 0 are common, 14 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈14
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Document only work that is solved and verified.
- Distinctive: line 27
Write only when the user asks to capture, save, or preserve the learning.
- Very specific: line 29
Write learnings only under openspec/learnings/ (one markdown file per learning) and edit only the context pointer in the resolved …
- Distinctive: line 34
Never record secrets, credentials, personal data, transient paths, incident details, dates, branch names, or change IDs as durable guidance.
- Distinctive: line 50
Use this counterfactual: if the config entry disappeared, would a capable future engineer still be likely to repeat the mistake or redo …
- Very specific: line 60
If the user names a registered OpenSpec store, or the work is explicitly in one, run openspec store list --json, resolve its ID, and keep …
- Very specific: line 64
Run openspec context --json from the current working directory, with the selected store flag when applicable.
- Very specific: line 68
Before the first write, run openspec list --json with the same root selection and require a non-null root.
- Very specific: line 72
Read <root.path>/openspec/config.yaml.
- Very specific: line 81
If evidence depends on a change and several active changes are plausible, run openspec list --json and ask the user to select one.
- Very specific: line 94
Use changeRoot, artifactPaths, and actionContext from the response.
- Very specific: line 106
Read the full resolved config and search its context, rules, and operations for the same idea.
- Distinctive: line 110
Update an existing entry when it is materially inaccurate or incomplete.
- Distinctive: line 111
Avoid synonyms that duplicate an existing rule.
- Distinctive: line 115
Place the learning in exactly one location:
- Distinctive: line 130
If the lesson is a product requirement or observable behavior, it belongs in a specification.
- Distinctive: line 135
If the lesson is useful only for one completed change and its design or final implementation already explains it, skip it.
- Distinctive: line 140
Write the smallest actionable statement that preserves the decision:
- Distinctive: line 145
Avoid broad words such as "always" unless the evidence establishes a real invariant.
- Distinctive: line 147
Keep artifact rules specific to that artifact and operation guidance specific to that operation.
- Very specific: line 150
Before editing, re-read the config and confirm the draft is still new and accurate.
- Very specific: line 156
Write the learning file under openspec/learnings/ (frontmatter name/description/type, minimal body, related links), add the one-line …
- Distinctive: line 166
Use the same store flag when applicable.
- Distinctive: line 170
If validation fails, restore valid YAML while preserving the intended learning, then rerun both checks.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
OpenSpec Learning
Capture one durable project learning as a markdown file in openspec/learnings/
and add a one-line pointer in openspec/config.yaml context, so future OpenSpec
workflows can find it.
Outcome
One qualifying learning is stored under openspec/learnings/ (one file per
learning, frontmatter name/description/type), a one-line pointer to it is
added to the resolved OpenSpec configuration's context, and both are validated
with the CLI. If no learning qualifies, write nothing and explain why.
Guardrails
- Capture exactly one learning per run.
- Document only work that is solved and verified.
- Write only when the user asks to capture, save, or preserve the learning. A question about possible lessons is read-only.
- Write learnings only under
openspec/learnings/(one markdown file per learning) and edit only thecontextpointer in the resolvedopenspec/config.yamlorconfig.yml. Do not edit code, specs, change artifacts, or archived artifacts in this workflow. - Preserve every unrelated config key, comment, rule, and operation entry.
- Never record secrets, credentials, personal data, transient paths, incident details, dates, branch names, or change IDs as durable guidance.
Durable Learning Bar
A learning qualifies only when all of these are true:
- The underlying behavior or solution has been verified.
- The reasoning is not readily recoverable from current code, tests, types, specs, or existing documentation.
- The lesson is likely to affect a future proposal, specification, design, task breakdown, implementation, or archive decision.
- Losing it would plausibly cause a repeated mistake, material risk, or substantial rediscovery.
- The claim is still true for the current tree.
Use this counterfactual: if the config entry disappeared, would a capable future engineer still be likely to repeat the mistake or redo substantial investigation? If not, skip the write.
Routine fixes, file locations, command output, implementation summaries, and facts already enforced by tests or types do not qualify. Effort and diff size do not make a lesson durable.
Root And Store Selection
If the user names a registered OpenSpec store, or the work is explicitly in
one, run openspec store list --json, resolve its ID, and keep --store <id>
on every supported OpenSpec command for the rest of the workflow.
Run openspec context --json from the current working directory, with the
selected store flag when applicable. Use root.path as the authoritative
project root. If it reports no_openspec_root, stop without creating one.
Before the first write, run openspec list --json with the same root selection
and require a non-null root. If a declared store cannot be resolved, report
the CLI's message and fix and stop.
Read <root.path>/openspec/config.yaml; use config.yml only when
config.yaml does not exist. If neither exists, stop and report that this
workflow requires an initialized OpenSpec configuration. Do not create a root
or choose a schema as a side effect.
Input
The user may provide a change name or a short context hint. Prefer the change
named in the request. Otherwise infer the completed work from the conversation.
If evidence depends on a change and several active changes are plausible, run
openspec list --json and ask the user to select one.
Workflow
1. Gather Evidence
For a selected change, run:
openspec status --change "<name>" --jsonUse changeRoot, artifactPaths, and actionContext from the response. Read
existing artifact paths returned by the CLI, then inspect only the relevant
implementation, tests, verification output, and current specs needed to verify
the proposed lesson. Do not treat completed task checkboxes as proof by
themselves.
Without a selected change, use the current conversation and the smallest relevant set of repository evidence. Never invent a lesson to make the run produce output.
2. Check Existing Guidance
Read the full resolved config and search its context, rules, and
operations for the same idea. Also check the relevant main spec or code when
needed to decide whether the fact is already discoverable.
Update an existing entry when it is materially inaccurate or incomplete. Avoid synonyms that duplicate an existing rule.
3. Choose The Destination
Place the learning in exactly one location:
| Learning type | Destination |
| Durable project fact, architecture invariant, domain constraint, or cross-cutting convention | file under openspec/learnings/ + one-line pointer in context |
| Guidance that changes how one artifact is authored | rules.proposal, rules.specs, rules.design, or rules.tasks |
| Guidance for implementation execution | operations.apply.guidance |
| Guidance for sync or archive decisions | operations.archive.guidance |
A learning file under openspec/learnings/ uses frontmatter
(name, description, type) in a <kebab-name>.md file, keeps the body to
the durable invariant plus a short “why”, and links related learnings
([[another-learning]] or related:). The config context pointer is one
line — the body lives in the file, never in config.
If the lesson is a product requirement or observable behavior, it belongs in a specification. Do not hide it in config and do not modify a spec in this workflow. Report the mismatch and recommend creating or updating an OpenSpec change.
If the lesson is useful only for one completed change and its design or final implementation already explains it, skip it.
4. Draft The Entry
Write the smallest actionable statement that preserves the decision:
- State what future work should assume or do.
- Include the reason only when it prevents a likely wrong alternative.
- Describe the current invariant, not the incident that revealed it.
- Avoid broad words such as "always" unless the evidence establishes a real invariant.
- Keep artifact rules specific to that artifact and operation guidance specific to that operation.
Before editing, re-read the config and confirm the draft is still new and
accurate. Keep a string context field within OpenSpec's 51,200-byte UTF-8
limit. Preserve valid YAML and the current schema or store declaration.
5. Write And Validate
Write the learning file under openspec/learnings/ (frontmatter
name/description/type, minimal body, related links), add the one-line
pointer in the resolved config's context, and keep the pointer line within the
51,200-byte context limit. Then run:
openspec doctor --json
openspec context --jsonUse the same store flag when applicable. Require a healthy resolved root and a successfully parsed context. Inspect the config diff and confirm only the one learning and any necessary YAML structure changed.
If validation fails, restore valid YAML while preserving the intended learning, then rerun both checks. Do not broaden the edit to fix unrelated validation findings.
Report
Report one of these outcomes:
- Captured: identify the config section, summarize the learning, name the evidence that qualified it, and report validation results.
- Updated: identify the corrected entry and why the previous wording was misleading or incomplete.
- Skipped: state which durable-bar condition failed or where the knowledge is already recoverable.
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.

