solid-skills: an Agent Skills package that pushes coding agents toward SOLID and TDD

The gap solid-skills is trying to close

Coding agents are good at producing code that runs and bad at producing code a team wants to maintain. The usual failure is not syntax. It is a 300-line service class with five responsibilities, domain primitives passed around as bare strings, and tests written after the fact to cover whatever the implementation happened to do. solid-skills addresses that by shipping opinionated written guidance the agent reads before it writes anything. The README frames the target plainly: transform junior-level code into senior-engineer quality software. The intended user is a developer who already has an agent wired into their editor or CLI and wants its output constrained by rules the team agreed on, not by the model's default style. The README states the skill is primarily designed for TypeScript and NestJS projects, with the caveat that it applies to any object-oriented codebase. That caveat is doing real work. A Python or Java team can read the same documents, but the worked examples will not match their syntax.

Nine reference documents and one instruction file

The mechanism is file layout, not executable code. Under skills/solid/ there is a SKILL.md that carries the main instructions, plus a references/ directory holding nine markdown files: solid-principles.md, tdd.md, testing.md, clean-code.md, code-smells.md, design-patterns.md, architecture.md, object-design.md and complexity.md. The agent loads SKILL.md when it judges the task relevant and pulls in the reference files as needed. That is the whole architecture. There is no parser, no AST pass, no build step. The quality of the output depends entirely on the quality of the prose in those files and on the agent's willingness to follow it. This is worth being clear about, because it means solid-skills cannot enforce anything. It can only instruct. If your agent ignores the instruction to write a failing test first, nothing in the package will stop it.

What the rules actually demand

The README lists the core principles as a table: TDD with a red-green-refactor cycle and tests before code, the five SOLID principles, clean code with meaningful names and small functions, GoF design patterns, and clean architecture with vertical slicing and a dependency rule. The key features section gets more specific and more debatable. It says the skill enforces TDD by requiring a failing test first, detects and fixes code smells, uses value objects for domain primitives such as IDs, emails and money, follows the Law of Demeter and Tell Don't Ask, and keeps methods under 10 lines and classes under 50 lines. Those last two numbers are the ones to think hardest about. A hard 10-line method limit is a useful forcing function for extracting helpers, but it also pushes logic into many small private methods, which can make a call stack harder to follow than one readable 25-line function would be. The 50-line class ceiling interacts badly with frameworks that expect a single class to declare many decorated handlers. The README does not explain how the skill resolves that tension in NestJS controllers, and that omission is the most interesting thing about the package.

Installing it and what lands on disk

Installation is one command: npx skills add ramziddin/solid-skills. The README states that skills become automatically available once installed and that the agent will use them when relevant tasks are detected. There is no config file, no environment variable and no registration step documented. The examples the README gives for triggering it are plain natural-language requests: implement a user registration feature, refactor this service to follow SOLID principles, review this code for quality issues, add tests for this module, design the architecture for a payment system. Because activation is inferred rather than declared, the practical question is whether your agent's skill loader picks up the directory at all. The README does not document where npx skills add places the files, so verify the install location against your agent's own skill discovery path before assuming it took effect. A silent no-op install would look identical to a working one until you read the generated code.

Where the package will fight you

Three limitations are visible from the material alone. First, the stack bias. TypeScript and NestJS are named as the primary target, so a team working in Go, Rust or a functional TypeScript style will find the SOLID and design-pattern guidance oriented toward class hierarchies they do not use. Second, the enforcement gap described above: this is documentation, and an agent that drifts mid-session will not be corrected by anything in the package. Third, the testing guidance presupposes that tests are wanted. On a legacy codebase with no test harness, a skill that insists on a failing test before any change can stall work rather than improve it. The README also does not state which agent runtimes are supported beyond the Agent Skills format link, and no releases are listed in the repository metadata, so there is no changelog to consult when behaviour changes between installs. That matters more here than for a normal library, because the artifact is prompt text and prompt text can be edited without a version bump.

How this differs from a linter or a style guide

The closest conventional alternative is ESLint with a plugin set such as eslint-plugin-sonarjs, which can flag cognitive complexity, duplicated branches and overly long functions. The difference in approach is mechanical rather than philosophical. ESLint parses your code and returns a violation at a line number; it cannot suggest that a class should be split along a seam you have not drawn yet, and it cannot write the test that would have caught the bug. solid-skills sits on the other side of that line. It cannot detect anything on its own, but it can shape what the agent produces before the code exists, which is where the design decisions are actually made. The two are complementary rather than competing: a linter gives you a deterministic gate in CI, and solid-skills gives you a bias in the generation step. If you want a rule enforced regardless of which model or agent is running, the linter is the only one of the two that will hold.

Maintenance cost and the licence position

The repository is MIT licensed according to the README, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive position, and it also means the package ships no warranty, so any code your agent generates under its guidance is your responsibility to review. Note the credits section: clean-code.md incorporates concepts from a Clean Code course summary by Academind GmbH and Maximilian Schwarzmuller, dated 2020. If you fork the package and redistribute it, that attribution is the part of the licence surface worth reading closely. On maintenance, the practical cost is low and unusual. There is nothing to upgrade in the dependency sense, no version pinning and no transitive packages. The cost is review time: someone on the team has to read the nine reference documents and decide whether they match your conventions, and re-read them when the agent's output starts drifting. The repository metadata shows a last push in September 2026 and no published releases, so treat the current main branch as the only version you can rely on.

Editorial conclusion

Adopt solid-skills if your agent already writes TypeScript or NestJS and you want its refactoring and test output steered by written rules rather than by whatever the model absorbed during training. Skip it if your stack is mostly functional or your team treats tests as an afterthought, because the skill's TDD requirement will fight your existing workflow. Before trusting it, open skills/solid/SKILL.md and check whether the class-under-50-lines and method-under-10-lines thresholds match your codebase, since those numbers will shape every suggestion the agent makes.

Official sources

1. Issues
2. ramziddin/solid-skills on GitHub
3. README