agentleFS
ishenliishenli/investment-agent/.claude/skills/openspec-learning/SKILL.md

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.

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
  1. Distinctive:

    Document only work that is solved and verified.

    line 26
  2. Distinctive:

    Write only when the user asks to capture, save, or preserve the learning.

    line 27
  3. Very specific:

    Write learnings only under openspec/learnings/ (one markdown file per learning) and edit only the context pointer in the resolved …

    line 29
  4. Distinctive:

    Never record secrets, credentials, personal data, transient paths, incident details, dates, branch names, or change IDs as durable guidance.

    line 34
  5. Distinctive:

    Use this counterfactual: if the config entry disappeared, would a capable future engineer still be likely to repeat the mistake or redo …

    line 50
  6. Very specific:

    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 …

    line 60
  7. Very specific:

    Run openspec context --json from the current working directory, with the selected store flag when applicable.

    line 64
  8. Very specific:

    Before the first write, run openspec list --json with the same root selection and require a non-null root.

    line 68
  9. Very specific:

    Read <root.path>/openspec/config.yaml.

    line 72
  10. Very specific:

    If evidence depends on a change and several active changes are plausible, run openspec list --json and ask the user to select one.

    line 81
  11. Very specific:

    Use changeRoot, artifactPaths, and actionContext from the response.

    line 94
  12. Very specific:

    Read the full resolved config and search its context, rules, and operations for the same idea.

    line 106
  13. Distinctive:

    Update an existing entry when it is materially inaccurate or incomplete.

    line 110
  14. Distinctive:

    Avoid synonyms that duplicate an existing rule.

    line 111
  15. Distinctive:

    Place the learning in exactly one location:

    line 115
  16. Distinctive:

    If the lesson is a product requirement or observable behavior, it belongs in a specification.

    line 130
  17. Distinctive:

    If the lesson is useful only for one completed change and its design or final implementation already explains it, skip it.

    line 135
  18. Distinctive:

    Write the smallest actionable statement that preserves the decision:

    line 140
  19. Distinctive:

    Avoid broad words such as "always" unless the evidence establishes a real invariant.

    line 145
  20. Distinctive:

    Keep artifact rules specific to that artifact and operation guidance specific to that operation.

    line 147
  21. Very specific:

    Before editing, re-read the config and confirm the draft is still new and accurate.

    line 150
  22. Very specific:

    Write the learning file under openspec/learnings/ (frontmatter name/description/type, minimal body, related links), add the one-line …

    line 156
  23. Distinctive:

    Use the same store flag when applicable.

    line 166
  24. Distinctive:

    If validation fails, restore valid YAML while preserving the intended learning, then rerun both checks.

    line 170

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 the context pointer in the resolved openspec/config.yaml or config.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:

  1. The underlying behavior or solution has been verified.
  2. The reasoning is not readily recoverable from current code, tests, types, specs, or existing documentation.
  3. The lesson is likely to affect a future proposal, specification, design, task breakdown, implementation, or archive decision.
  4. Losing it would plausibly cause a repeated mistake, material risk, or substantial rediscovery.
  5. 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>" --json

Use 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 typeDestination
Durable project fact, architecture invariant, domain constraint, or cross-cutting conventionfile under openspec/learnings/ + one-line pointer in context
Guidance that changes how one artifact is authoredrules.proposal, rules.specs, rules.design, or rules.tasks
Guidance for implementation executionoperations.apply.guidance
Guidance for sync or archive decisionsoperations.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 --json

Use 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.

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.