serenity-skill: an Agent Skill that turns a hot theme into a ranked supply-chain research list
Serenity-inspired Agent Skill for supply-chain bottleneck stock research
At a glance
- What is it?
- serenity-skill packages a public supply-chain research method into an installable SKILL.md plus a local Python scorecard, aimed at investors who want a first-pass research queue rather than a buy signal. The method is the product; the code around it is small.
- Who is it for?
- Adopt serenity-skill if you already read filings, exchange documents and earnings calls yourself and want the AI to produce the first-pass layer map and candidate queue before you start. Do not adopt it if you want a ranked list you can act on without opening a primary document, or if your process is quantitative screening rather than narrative research.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem serenity-skill targets: theme heat without a research queue
The README opens from a specific frustration. A reader sees AI semiconductors, robotics, CPO, compute, power equipment or innovative drugs trending, feels the heat, and still cannot say which part of the chain to look at, which company sits closest to it, or which fund direction reflects it. That gap between sensing a theme and having a research plan is what the project claims to close.
The intended user is an investor who already follows these themes but lacks a repeatable filter. The README frames the deliverable as a prioritised research list, not a trade. It states plainly that the Skill handles research, ranking and reasoning, and that the final buy or sell decision stays with the user. That boundary is repeated in the research-boundary section, which also says the project is research support only and does not provide execution, account operations or return promises.
So the audience is narrow in a useful way. It is not for someone who wants a signal service, and it is not for someone who has no interest in reading announcements, exchange filings or earnings transcripts, because the method's evidence requirements push you back to those documents. It is for the person who already does that reading and wants the first hour of it structured.
From theme to chokepoint: the layered decomposition the Skill walks through
The mechanism described in the README is a fixed sequence. Start from a large theme and ask where the real demand originates. Decompose the theme into layers: downstream demand, system integration, chips and components, equipment, materials, packaging and testing, and infrastructure. Inside those layers, look for the segments that are hard to route around: few suppliers, long qualification cycles, difficult capacity expansion, strict customer certification, high material purity requirements. Then map back to stocks and fund directions and judge which candidates sit near a real bottleneck and which are mainly riding the theme. Finally, check announcements, financials, inquiry letters, orders, capacity, customers and risks, and produce a priority ordering.
The README's own summary of the borrowed method is that in a large move, the valuable opportunities often hide in the link that is hardest to bypass when a system expands. That sentence is the whole thesis of the Skill, and everything else is procedure around it.
Two design choices stand out. First, the evidence requirement is explicit: strong conclusions should rest on announcements, exchange documents, financials, earnings calls, regulatory and project filings, patents, standards, credible media and professional analysis, with social media treated as a lead source only. Second, the output format is a structured list with named next checks, not a rating. The sample output in the README shows a ranking of companies, a note on which theme is being deprioritised and why, and a three-item list of things to verify next. That last part is the most useful piece of the design: the Skill is instructed to end on open questions rather than a verdict.
Installation: copy the skill directory, then keep the repo layout intact
There is no package to install. The README gives copy commands that place SKILL.md, LICENSE, references/, assets/, scripts/, examples/ and agents/ into a client-specific skills directory. For Codex and generic Agent Skills clients, the user-level path is $HOME/.agents/skills/serenity-skill and the project-level path is .agents/skills/serenity-skill. For Claude Code, the equivalents are $HOME/.claude/skills/serenity-skill and .claude/skills/serenity-skill. Hermes Agent uses $HOME/.hermes/skills/research/serenity-skill. Other AgentSkills-compatible clients get the same directory contents dropped into their own serenity-skill folder.
The README notes that README.md and the maintenance documents are for GitHub display and do not need to be installed into the runtime directory. That is a small but real detail: the runtime payload is the skill file plus its references, assets, scripts, examples and agents folders.
The Python side is a single script with two modes. To generate a scorecard template, run python scripts/serenity_scorecard.py --template > my-company.json. To score a filled template and get Markdown out, run python scripts/serenity_scorecard.py --format md my-company.json. There is also a validator, python scripts/validate_skill.py ., which checks the skill directory itself. The README does not state a minimum Python version or list third-party dependencies, so whether the script runs cleanly on your interpreter is something you have to check locally rather than assume. The repository also ships evals/test-cases.md, which suggests the skill file is meant to be regression-checked, though the README does not describe how those cases are executed.
The scorecard is local and manual, and that is the main limitation
The bottleneck scorecard is the only computational component, and it is a form-filling exercise. You generate a JSON template, you populate it, you run it, and you get Markdown. Nothing in the README suggests the script fetches filings, parses financial statements or pulls market data. The evidence gathering the method depends on is done by the agent with web access, using the prompts in assets/research-prompt-pack.md and the workflow in references/deep-research-workflow.md.
That produces a predictable failure mode. The quality of the output tracks the quality of the model's retrieval and your own inputs, not the script. If the agent cannot reach a filing, or reaches a summary of a filing, the evidence ladder in references/evidence-ladder.md is the only thing standing between you and a confident-sounding ranking built on secondary sources. The README acknowledges this by insisting that social media is a lead source and that strong conclusions require primary documents, but a prompt instruction is not an enforcement mechanism.
There is a second boundary. The method is built for themes with a physical supply chain: chips, optics, robotics components, power equipment. Applied to a theme where the bottleneck is regulatory, distribution or brand rather than manufacturing capacity, the layer decomposition has less to bite on. And because the output is a research queue with explicit next checks, it will feel incomplete to anyone who wants a ranked list with scores attached and nothing else. That incompleteness is deliberate, but it is still a cost.
How this differs from a quantitative screener
The natural comparison is a factor screener or a financial-data terminal. Those tools start from numbers: you define a universe, filter on valuation, growth, margin or momentum, and get a ranked list of tickers. The output is reproducible, the inputs are standardised, and the ranking is only as good as the factor you chose.
serenity-skill inverts the order. It starts from a narrative about demand and works downward through a supply chain until it reaches a segment where capacity is hard to add. Numbers enter late, as evidence for or against a candidate's position near that bottleneck. The README's example prompt asks the agent to check announcements, financials, inquiry letters, investor-relations responses, tenders, environmental and energy assessments, patents, customer certification and financial quality, which is a reading task, not a screening task.
The practical difference is what you get. A screener tells you which companies pass a numeric filter today. serenity-skill tells you which layer of a theme deserves attention and which three documents to read next. The first is faster and repeatable; the second is slower and depends on the model's reading. If your edge comes from a factor you have already validated, the screener is the better tool and this Skill adds nothing. If your edge comes from noticing which link in an expanding system is hardest to replace before the market prices it, the Skill is aimed at exactly that step, and the screener would not have surfaced it.
Maintenance, licence and what the MIT terms do not cover
The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. The install commands copy LICENSE alongside SKILL.md, which keeps that notice in the runtime directory. The README states that README.md and the maintenance documents are not needed at runtime, so if you trim the copied files, keep LICENSE.
The MIT grant covers the code and the written material. It does not cover the underlying research method, which the README describes as a public methodology project inspired by the observable research pattern in Serenity / @aleabitoreddit's public content. The README also states the project is independent of that account. If you plan to redistribute the Skill inside a product, the licence question is settled for the files; the attribution question around the method is a separate matter and not one this review can resolve.
Maintenance cost is low by construction. There are no runtime dependencies described, no service to keep alive and no data feed to renew. The upkeep is the scorecard weights in assets/bottleneck-scorecard.json and the reference documents under references/, which encode the criteria the agent applies. When your view of what counts as a chokepoint changes, those files are what you edit. The last push recorded for the repository is 2026-05-05, and no releases are listed, so distribution is by copying the working tree rather than by versioned artifacts. That means you should record which commit you copied if you need to reproduce a result later.
Who should install it, and what to check before trusting a ranking
Install it if you research themes with physical supply chains and you want the first pass done before you open a filing. The prompts in assets/research-prompt-pack.md are usable as-is, and the challenge prompt (asking the agent to argue that a company is not a core supplier of a given theme) is the most valuable one in the set because it forces the evidence question rather than the narrative one.
Do not install it if you need a ranking you can act on without reading primary documents, or if your theme has no manufacturing layer to decompose. The Skill will still produce output in those cases, and that output will look the same as the output in the cases where it is well grounded. That symmetry is the risk.
Before you rely on any ranking it produces, run the validator with python scripts/validate_skill.py . to confirm the skill directory is intact, then generate a scorecard with python scripts/serenity_scorecard.py --template and inspect the fields: those fields are the criteria the method actually applies, and they are the fastest way to see whether its definition of a bottleneck matches yours. If the fields do not match, edit assets/bottleneck-scorecard.json before you run a real research prompt, because the prompt templates and the scorecard should be applying the same standard.
Editorial conclusion
Adopt serenity-skill if you already read filings, exchange documents and earnings calls yourself and want the AI to produce the first-pass layer map and candidate queue before you start. Do not adopt it if you want a ranked list you can act on without opening a primary document, or if your process is quantitative screening rather than narrative research. Before installing, verify three things: that SKILL.md and the references/ directory load in your specific client (the README lists several paths, and the copy commands assume the repository layout is intact), that scripts/serenity_scorecard.py runs on your Python version by generating a template with the --template flag, and that the scoring weights encoded in assets/bottleneck-scorecard.json match the bottleneck criteria you actually care about, since those weights are the part of the method most likely to disagree with your own.
Community notes