Skilldeck: Agent Skills That Read Your Repo Before Coding
Skilldeck packs 36 agent skills for JS and TS that detect your conventions before picking a stack. The decisions, dead ends, and what 1.0 taught me.
Jonathan Juliani
Sr Software Engineer - Full Stack · WithClutch Inc. | Juliani Tecnologia
Node.jsTypeScriptAIClaude CodeCursorOpen Source
You install agent skills and, on the first task, the assistant swaps the repo's Jest for Vitest, or npm for pnpm, or pulls in a library nobody on the team asked for.
The skill stopped reading the project and started deciding for it.
That is why I built skilldeck: 36 skills (at the time of writing) for JavaScript and TypeScript that read the repository first and recommend second. This post is a retrospective from concept, version 0.1.0 to 1.0.2, covering the three main decisions that mattered and what is still rough.
What you will learn:
Why I built another skill pack
Which skills shaped it
If it replaces other packs and why you should use it or not
Stacks the same skills still serve, from Jest and npm to Express, NestJS, and Redux Toolkit
Why most of the pack is engineering, and where a companion like caveman fits in
The precedence chain: a project or company standard outranks the skill
Why there is one marketplace, not several for each "category"/"subject"
What Cursor refuses (symlinks) and how I worked around it [work in progress to fix this]
What I would do differently, and what I do not know yet
What comes next for skilldeck
Why another set of agent skills?
A lot of packs I tried are built around one stack, or around one harness. That is a real choice, and several of them are why these skills exist. Skilldeck takes the other choice: one set of skills, patterns, standards, and helpers, applied on top of whatever the project already uses.
I tried to design it to be a companion that will not interfere with the project's stack, but rather help it along, and of course, if needed, provide alternatives and improvements.
It stays mostly quiet about vendors. It tries to define and rely on community preferences and patterns based on my experience, new packages and community tools that are emerging in the ecosystem, and also rely on any project convention or a company standard that is already defined/built-in in the project, that will outrank the skill whenever one exists. The repository's tagline sums it up:
Subscribe to the Engineering Ledger
Get architecture and performance notes in your inbox. Same list as the timed prompt—subscribe here anytime.
Detect before you decide.
Recommend before you impose.
Ask before you assume.
Prove before you claim.
The same skills run on Claude Code, Cursor, Codex, Gemini, and possibly others that use .agents setup, I confess that I was not able yet to test them all (and I appreciate your help with that). They also run when the repo is already on Jest, npm, Express, NestJS, Redux Toolkit, Cypress, Prisma, or CSS Modules (those show up all the time, and the skill's job is to work with them). A legacy npm/Jest service, a pnpm/Vitest monorepo, and a fresh Expo app get the same help.
A few skills shaped and inspired pieces of this pack. They are still the ones I open when I want that piece or something specific at full depth:
Skilldeck keeps that shared set. Those packs stay separate, and so does any preferred stack. The goal is the same skills, patterns, standards, and helpers, on the tool the project or the company already chose.
There are 36 skills in four groups:
Group
Skills
Foundation
3
Engineering
22
Design
6
Process
5
22 of the 36 are engineering. Design and process are part of the pack. The weight is engineering, and those skills are the ones that write the most, so a companion that cuts output tokens improves the whole session. caveman does that. It sits beside skilldeck (it is not one of the 36), and the engineering work stays, with less prose around it.
Each group on its own. Foundation detects, sets up, and writes the instructions file.
Engineering is the heavy group, drawn on the four rungs from the pack map.
Design decides the surface before anything is built.
Process sits around the work: align, investigate, plan, draw, look back.
Timeline: 0.1.0 to 1.0.2
Eight releases in two weeks. Most of the 0.1.x line was install and naming fixes, not content.
Version
Date
What changed
0.1.0
Oct 7
Baseline
0.1.1
Oct 8
Install and naming fixes
0.1.2 to 0.1.4
Oct 9
More install and naming fixes
1.0.0
Oct 9
Release 1.0
1.0.1
Oct 16
Mermaid skill map in the README
1.0.2
Oct 21
OpenAI zip attached to each release
1.0.0 shipped the same day as 0.1.4. The three decisions below are what the collection has rested on since.
Decision 1: a precedence chain for agent skills
A skill that swaps the stack is deciding for the repo, so the first decision was who wins over whom. The chain stops at the first tier that answers:
Think of a developer who just joined a team. They do not rewrite everything in their favorite stack on day one. They read how the code is already written, then the company guide, and only fall back on personal taste when neither says anything. The chain is that, for the agent.
In practice:
Project: what the agent detects in the repo (package manager, test runner, structure) always wins.
Company: team standards apply after what the code already shows.
Personal: breaks ties, never decides.
Community: applies only to new (greenfield) projects, and the agent offers it with a reason and waits for confirmation. Nothing is applied silently.
A repo on Jest and npm, or a company standard that says the same, is the answer. The community snapshot can prefer Vitest and pnpm. The skill does not swap them.
So, why not just write a good AGENTS.md?
Because a skill description only reaches the model when something goes looking for it, while a file read every turn always does. So setup-skills can optionally write a verification block and a routing block into AGENTS.md or CLAUDE.md. The skill teaches; the file makes sure the agent remembers.
A fair objection: detection costs time and tokens. It does. Getting the stack wrong costs more, because you only find out in code review.
Decision 2: one marketplace
A marketplace here is the catalog an agent installs plugins from. Skilldeck has one. Claude Code, Cursor, Codex, Gemini, and Copilot all install from that same catalog, and the install id is skilldeck@skilldeck.
A second marketplace is a second copy of the same skills. The agent cannot tell which copy is current, so it asks you to pick one. Each tool has its own manifest, and every manifest describes that one plugin. The validator keeps them in sync, so they cannot drift into two packs.
One more cost me time: installing the plugin and running npx skills loads every skill twice, and the agent asks you to "Pick one". It cannot tell which copy is the real one, which is fair. The docs now say to choose a single path.
Decision 3: About Cursor and symlinks
This one hurt. I open Cursor, import from GitHub, and get no skills. None. Then I look at the layout and there it is: the pack was a symlink pointing out of plugins/skilldeck.
A symlink is a folder shortcut, like a desktop shortcut pointing at the real file somewhere else. Claude follows the shortcut. Cursor does not.
The fix was to invert it: the real files now live in plugins/skilldeck/, and the root skills/ folder is the shortcut pointing at them, so npx skills keeps working. Pointing Claude's source straight at the root (./) is valid for Claude, but Cursor rejects it, so the files stay inside plugins/skilldeck/.
Two smaller traps of the same family:
A skill description with an unquoted colon becomes a YAML mapping instead of text. validate.py now checks for it.
Skills that call each other can form cycles. validate.py also detects cycles in the call graph.
Descriptions now follow one shape: what the skill does, "Use when", and "Not for". That helps the agent pick the right skill instead of firing two.
What I would do differently
A few things I would do differently:
I would test installation on every target agent before publishing the first version: The initial releases after the baseline were mostly install and naming fixes, and a basic install test would have caught them. I also skipped the Codex and Gemini acceptance commands in phase 1 because neither was on my PATH/installed, and that is still debt.
I would and probably will check and adapt the skills to be more compatible with other programming languages and frameworks, and not just JavaScript/TypeScript ecosystems.
I would focus a little more on other bigger areas like system design, security, observability, and process rather than focusing more in coding conventions/standards. But hey, look at what is coming next bellow, I'm working exactly on that.
What I do not know yet
I do not know whether a four-level precedence chain is simple enough for other people or only for me.
I also have not tested skilldeck outside the JS/TS ecosystem, which is something I want to do and will do soon.
I have not measured whether the AGENTS.md blocks change agent behavior on long tasks.
It's a constant work in progress, and I'm happy to have you help with that.
What comes next for skilldeck
The next round will probably include some of the debts above, not sure when yet but soon:
Run the Codex and Gemini acceptance commands that were skipped.
Measure whether the AGENTS.md blocks change agent behavior on long tasks, instead of assuming they do.
Test installation on other target agents.
Alongside that, as I work on different projects and products, it's already drafted and I'm currently curating/testing a few companion skills that will tackle some system design, security, observability, and process topics.
The skills won't grow, the bellow are companions that will only be triggered when the task is about that topic and needs them:
api-design gets idempotency. The key names one attempt, and every retry of that attempt reuses it (a new key on the retry is how the same attempt runs twice). The same key with a different body is a conflict.
data-model gets money and transactions. An amount is an integer in minor units, with a currency, and the server recomputes the total. Two writers do not read a quantity and both write it back. A call to another system stays outside the database transaction.
frontend-craft gets a resilient client, and rules for an unattended or shared device. A request has a timeout. A timeout is an unknown outcome, so the screen checks status instead of inviting a second submit. A shared screen resets when it sits idle, and the recovery copy assumes nobody is there to ask.
testing-strategy gets failure paths. The test asserts what was stored, not how many times a function was called.
state-management keeps in-flight work in session storage, with the idempotency key, so a reload resumes the same attempt.
security-hardening names what a card may leave behind: a token, the last 4 digits, the brand, and the expiry. The full number and the security code are never stored.
ts-standards says the same thing about money, in one line. design-brief names an unattended or shared device as a surface, and design-review asks whether a stranger on that surface can recover alone.
bootstrap-repo asks for a readme a stranger can follow. verify-before-done runs that readme in a clean environment only when the claim is that they can.
Detected project > company > personal (tiebreaker) > community (new projects only, confirmed)
One marketplace
One catalog, install id skilldeck@skilldeck. A second catalog is a second copy the agent cannot tell apart
Cursor and symlinks
Real files in plugins/skilldeck/, root skills/ as the symlink
Install
Plugin or npx skills, never both
Weight
22 of 36 are engineering. A project or company standard wins. Caveman-style compression is a companion, not a skilldeck skill
Your turn
Which convention in your repo does your AI assistant ignore every single time, no matter how often you explain it? Tell me, because that is where the next skill comes from. Reply in the comments or through the newsletter.
