Investor Skills: Portable Investor Judgment as SKILL.md Packages

The gap Investor Skills tries to close

Most prompt libraries for finance give an agent a persona and a tone. Investor Skills gives it a structure. The repository describes itself as a library that turns investing judgment into portable, structured formats, and the unit of distribution is a directory: a SKILL.md that acts as the agent entry point, plus an optional invest.md that holds the investment system the skill applies. That split is the whole idea. The SKILL.md answers when to use the model, what inputs are required, how to apply the process, what to avoid, and how to format the answer. The invest.md answers what the investor believes: worldview, universe, market regime, signals, filters, sizing, risk, monitoring and playbooks. The intended reader is not a discretionary trader looking for tips. It is someone building an agent that needs to reason about a position, and someone studying a named investor's method closely enough to write it down as fields. The README is explicit that the free layer is for study, research and agent workflows, and that execution-grade, trade-labeled judgment sits behind Questflow's paid tier.

How a skill package is structured and loaded

The layout is deliberately shallow. A skill lives at skills/<skill-name>/, with SKILL.md required and invest.md optional. The frontmatter of SKILL.md carries a name, a description that states the trigger condition, and an invest key pointing at the schema file. The repository's own example frontmatter uses name: buffett and description: "Use when evaluating a business through Buffett-style ownership, moat, owner earnings, and margin-of-safety judgment." That description is doing real work: it is the routing signal an agent harness reads to decide whether this skill applies to the current question. The schema file mixes two formats in one document. YAML frontmatter holds machine-readable tokens (signals, filters, sizing rules, risk parameters, key metrics) and the Markdown body holds human-readable philosophy, analysis process, execution rules and behavioral guardrails. In the Buffett/Munger example, signals are nested by category with per-signal weight, frequency, direction and threshold, while sizing and risk are flat keys such as maxPosition: 25%, maxPortfolio: 15, marginOfSafety: 30% and stopLoss: none. The data flow is therefore one-directional and stateless: harness selects a skill by description, reads the schema, applies the thresholds and filters to whatever market or portfolio context the harness supplies, and formats the answer as SKILL.md instructs. Nothing in the repository fetches prices or places orders.

Using an investor skill in your agent

There is no package manager step. The README's Quick Start section is titled "Use an investor skill" and the instruction is to copy a skill package into your agent. The repository is a plain checkout, so the first real action is cloning it and looking at what a package contains.

git clone https://github.com/questflowai/investorskills.git

After cloning, the top-level layout is the one the README documents: LICENSE, README.md, assets/, docs/, examples/, scripts/, skills/ and templates/. If skills/ holds no packages in your checkout, that is expected: the layout documents skills/<skill-name>/ as the location for packages, and the README points contributors at templates/skill.template.md to create new ones. From there, a minimal skill is a directory you create yourself. The frontmatter below is the shape the README shows for the Buffett skill, with invest pointing at the sibling schema file.

---
name: buffett
description: Use when evaluating a business through Buffett-style ownership, moat, owner earnings, and margin-of-safety judgment.
invest: ./invest.md
---

To see what a filled-in schema looks like before writing your own, open the standalone example. It is the only complete investment system shipped in the repository.

cat examples/buffett.invest.md

You should see the same YAML keys the README quotes: version, name, slug, style, timeHorizon, decisionCadence, assetClasses, universe, marketRegime, then signals, filters, sizing and risk. Copy templates/invest.template.md to a new file, fill the fields, point a SKILL.md at it, and drop the directory into your harness's skill path. The README states the packages work in Claude Code, Codex, Cursor, OpenCode, or any other agent harness that can read SKILL.md instructions, so the install step is whichever path that harness uses for skill directories.

The schema is a contract, and thin contracts fail quietly

The strongest design decision here is also the source of the main limitation. Everything is text with no runtime, which means nothing validates your schema. A misspelled key such as marginOfSafty, a threshold written as 15 instead of "> 15%", or a signal category the agent does not recognize will not raise an error. The agent will simply reason without that constraint, and the output will look plausible. The README does not document a validator, and the repository layout shows no schema-checking tool under scripts/ or elsewhere. This matters because the fields carry very different weight. Filters such as durableMoat: required and consistentFCF: required read as hard gates, while signal weights like weight: high are soft. An agent that treats a soft weight as a gate will reject good candidates; one that treats a required filter as advisory will pass bad ones. There is also a versioning question the material leaves open: the example schema carries version: alpha, and the docs describe INVEST.md as an optional standalone format, but the README does not document a migration path between schema versions. If you build a library of skills, plan to review the YAML by hand after every edit.

Where this is the wrong tool

Investor Skills is not a backtesting framework, a screener, or an execution layer. It contains no market data pipeline, no broker integration and no historical price store. The README's framing is that skills explain, monitor, size, invalidate and execute within explicit risk rules, but the execution half belongs to Questflow's harness, which the README describes as combining models, skills, plugins and execution accounts across market data, portfolio context, broker/exchange/wallet permissions and fund workflows. If you want to know whether a Buffett-style screen would have outperformed an index over twenty years, this repository cannot tell you and does not claim to. The other mismatch is scope of judgment. The README states plainly that Questflow's exclusive closed-source skills are distilled from top traders by labeling judgment across real trades, and that they are available to paid members. The public skills are the study layer. Anyone who needs trade-labeled, execution-grade judgment is looking at the wrong tier of the project, and the README says so rather than hiding it.

Alternatives and the actual difference in approach

The closest comparison is not another investing library but the general-purpose skill and prompt ecosystems that agent harnesses already ship. Those give you a directory of instructions with no domain schema: the model decides what a good answer looks like. Investor Skills adds a typed middle layer. Signals carry weight, frequency, direction and threshold; sizing carries maxPosition and maxPortfolio; risk carries marginOfSafety and stopLoss. That structure is what makes two skills comparable and what lets a harness route on a description rather than on a keyword. The cost is rigidity. A free-form prompt can absorb a novel situation by improvising; a schema with universe.marketCap: large-cap and liquidity: high will push the agent back toward that box, and the agent has no documented way to declare the schema inapplicable. A second comparison point is the reading list, podcast list and YouTube list under docs/. Those are curated source material per skill, and the README's suggested workflow is to use the skill first, then use the readings to understand, stress-test and enrich it. That is a different posture from a link dump: the references exist to challenge the encoded model, not to decorate it.

Licence, maintenance and the cost of keeping skills current

The repository is MIT licensed, with a LICENSE file at the top level. In practice that means you can copy the templates, the spec and the example into your own product, including a commercial one, provided you keep the licence notice. It does not grant you the closed-source Questflow skills, which the README places behind paid membership and outside this repository. The last push to the default branch was on 2026-08-23, and the repository is not archived, so the codebase is recent. Upgrade cost is the part worth thinking about before you commit. Because skills are text, there is no dependency graph to break, but there is also no automated way to know when docs/spec.md changes in a way that invalidates your YAML. The spec is described as documenting the optional standalone INVEST.md format, and the README treats INVEST.md as conceptually the same thing as the schema inside a skill, so a spec revision can ripple into every skill you have written. Budget for a periodic diff of docs/spec.md and templates/invest.template.md against your own skill directories rather than for a version bump.

Editorial conclusion

Adopt Investor Skills if you want investor judgment expressed as inspectable text files that an agent can load, and you are willing to write the judgment yourself from the templates. Do not adopt it if you expect a working trading system, backtested signals, or execution permissions: the repository is a format and a reference library, and the execution-grade skills are closed source. Before you commit, read docs/spec.md end to end and diff templates/invest.template.md against examples/buffett.invest.md to see which fields the spec requires and which the example actually fills in.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. questflowai/investorskills on GitHub
5. README