Skip to content
Back to search

solid-engineering

A practical engineering standard for AI coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ramsyparker--solid-engineering/badge.svg)](/listings/ramsyparker--solid-engineering)

HTML

<a href="/listings/ramsyparker--solid-engineering"><img src="/api/listings/ramsyparker--solid-engineering/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires **Node.js 22+** and a supported agent with local skills enabled. Run from the project where you want the skill:

npx @aaramsyy/solidengineering install

Version **0.2.0+** installs all three skills by default under `<current-directory>/.agents/skills/` for **Codex**. If your npm version is older, use the GitHub Release archive below for the new commands. Reload your agent session, then try:

Use $solid-engineering to audit this repository. Report evidence and severity. Do not edit files.

Choose another agent:

npx @aaramsyy/solidengineering install --agent claude
npx @aaramsyy/solidengineering install --agent cursor

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 235 lines
  1. # SOLID Engineering
  2. **A practical engineering standard for AI coding agents.**
  3. Created by **aaramsyy** | [GitHub](https://github.com/ramsyparker/solid-engineering) | [npm](https://www.npmjs.com/package/@aaramsyy/solidengineering) | [Releases](https://github.com/ramsyparker/solid-engineering/releases) | [Issues](https://github.com/ramsyparker/solid-engineering/issues)
  4. Install a set of focused skills that guides your agent through repository reconnaissance, evidence-based auditing, focused implementation, and verification. Apply SOLID, separation of concerns, and pragmatic engineering judgment without demanding unnecessary classes, layers, or rewrites.
  5. Supports **Codex, Claude Code, and Cursor** through their local skill directories. The installer has **zero runtime dependencies** and no automatic install hooks.
  6. ## Quick start
  7. Requires **Node.js 22+** and a supported agent with local skills enabled. Run from the project where you want the skill:
  8. ```sh
  9. npx @aaramsyy/solidengineering install
  10. ```
  11. Version **0.2.0+** installs all three skills by default under `<current-directory>/.agents/skills/` for **Codex**. If your npm version is older, use the GitHub Release archive below for the new commands. Reload your agent session, then try:
  12. ```text
  13. Use $solid-engineering to audit this repository. Report evidence and severity. Do not edit files.
  14. ```
  15. Choose another agent:
  16. ```sh
  17. npx @aaramsyy/solidengineering install --agent claude
  18. npx @aaramsyy/solidengineering install --agent cursor
  19. ```
  20. ## Available skills and commands
  21. | Skill | Purpose | Claude Code / Cursor | Codex CLI / IDE |
  22. | --- | --- | --- | --- |
  23. | `solid-engineering` | Full engineering workflow, implementation, and verification | `/solid-engineering` | `$solid-engineering` |
  24. | `refactoring` | Improve structure while preserving observable behavior | `/refactoring` | `$refactoring` |
  25. | `code-audit` | Read-only review with evidence and prioritized findings | `/code-audit` | `$code-audit` |
  26. In Claude Code or Cursor, type `/` in agent chat and select a skill. In Codex CLI or the IDE extension, use `/skills` to select a skill or type `$` to mention it. Do not assume `/refactoring` registers as a custom Codex slash command. These are agent instructions invoked in chat, not terminal commands or new MCP tools. Existing agent tools perform the work.
  27. ```text
  28. /refactoring src/billing - simplify responsibilities without changing behavior
  29. /code-audit src/auth - report findings without editing code
  30. /solid-engineering implement pagination and verify the affected flow
  31. ```
  32. For Codex, use `$refactoring`, `$code-audit`, or `$solid-engineering` with the same task description. Discovery depends on your agent version and configuration. See the official [Codex invocation guide](https://learn.chatgpt.com/docs/build-skills), [Claude Code skills guide](https://code.claude.com/docs/en/skills), and [Cursor skills guide](https://cursor.com/docs/skills).
  33. Each skill is self-contained and can be installed alone:
  34. ```sh
  35. npx @aaramsyy/solidengineering list
  36. npx @aaramsyy/solidengineering install --agent claude --skill refactoring
  37. npx @aaramsyy/solidengineering install --agent cursor --skill refactoring --skill code-audit
  38. ```
  39. `list` shows the bundled skill catalog, not the skills already installed in your project.
  40. ### Other package managers
  41. Choose one equivalent command:
  42. ```sh
  43. pnpm dlx @aaramsyy/solidengineering install
  44. bunx @aaramsyy/solidengineering install
  45. ```
  46. Bun's default executable handling honors the Node.js shebang, so Node.js is still required. Multi-skill installation and `--skill` require version 0.2.0 or newer; older versions install only `solid-engineering`.
  47. `npm install @aaramsyy/solidengineering` downloads the package but does not copy the agent skill. Run the explicit CLI `install` command to perform that step.
  48. ### GitHub Packages
  49. The GitHub Packages distribution uses **`@ramsyparker/solidengineering`**, matching the repository owner's namespace. The npm distribution remains **`@aaramsyy/solidengineering`**. Matching versions provide the same skills and installer; registry releases may differ.
  50. GitHub's npm registry requires authentication to download packages, including public packages. Use a GitHub personal access token (classic) with `read:packages` when prompted for the password:
  51. ```sh
  52. npm login --scope=@ramsyparker --auth-type=legacy --registry=https://npm.pkg.github.com
  53. npx --registry=https://npm.pkg.github.com @ramsyparker/solidengineering install
  54. ```
  55. Add `--agent claude` or `--agent cursor` to select another agent. For installation without GitHub registry authentication, use the npm quick start or the GitHub Release archive below. See [GitHub's package authentication documentation](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-to-github-packages).
  56. ## The full engineering workflow
  57. | Stage | Expected behavior |
  58. | --- | --- |
  59. | Reconnaissance | Inspect instructions, architecture, dependencies, and real application flows before editing. |
  60. | Audit | Report actionable findings with evidence, impact, and Critical / High / Medium / Low severity. |
  61. | Plan | Prioritize risk, define acceptance criteria, and choose the smallest safe implementation. |
  62. | Implement | Make focused changes and preserve established contracts. |
  63. | Verify | Run relevant configured checks and report observed results. |
  64. | Regression review | Check affected features, permissions, data integrity, and failure paths. |
  65. | Final review | Inspect the complete diff and report limitations and unverified requirements. |
  66. The supporting checklist covers design, reliability, security, performance, and compatibility. Depth scales to the task: a narrow fix should not become a repository-wide redesign.
  67. **Audit-only requests stay read-only.** Implementation requests continue through verification. The skill does not grant additional permissions, authorize destructive actions, or guarantee production readiness. Review and testing remain necessary.
  68. Read the [skill instructions](skills/solid-engineering/SKILL.md) and [engineering checklist](skills/solid-engineering/references/engineering-standard.md).
  69. ## CLI reference
  70. ```text
  71. npx @aaramsyy/solidengineering install [options]
  72. ```
  73. | Option | Behavior |
  74. | --- | --- |
  75. | `--agent <name>` | Target `codex`, `claude`, or `cursor`. Default: `codex`. |
  76. | `--skill <name>` | Install only the named skill. Repeat to select multiple skills. Default: all three. |
  77. | `--global` | Install under your home directory for use across projects. |
  78. | `--dir <path>` | Custom parent skills directory; the installer creates one subdirectory per selected skill. |
  79. | `--dry-run` | Print the destination without writing. Does not validate writability or conflicts. |
  80. Top-level commands, without `install`:
  81. ```sh
  82. npx @aaramsyy/solidengineering --help
  83. npx @aaramsyy/solidengineering --version
  84. ```
  85. No arguments also shows help. Unknown arguments fail with a nonzero exit code. Use separate option values (`--agent claude`), not `--agent=claude`.
  86. ### Installation locations
  87. | Agent | Project path | Personal path (`--global`) |
  88. | --- | --- | --- |
  89. | Codex | `<cwd>/.agents/skills/<skill-name>` | `<home>/.agents/skills/<skill-name>` |
  90. | Claude Code | `<cwd>/.claude/skills/<skill-name>` | `<home>/.claude/skills/<skill-name>` |
  91. | Cursor | `<cwd>/.cursor/skills/<skill-name>` | `<home>/.cursor/skills/<skill-name>` |
  92. `<cwd>` is where you run the command; the installer does not search for a repository root. `<home>` is your operating system's user home directory.
  93. ```sh
  94. # Preview the destination
  95. npx @aaramsyy/solidengineering install --dry-run
  96. # Install for Claude Code across projects
  97. npx @aaramsyy/solidengineering install --agent claude --global
  98. # Install under a custom parent directory
  99. npx @aaramsyy/solidengineering install --dir "./team skills"
  100. ```
  101. Relative custom paths resolve from the current directory. `--global` and `--dir` cannot be combined. A custom directory must be discoverable by your agent or configured separately.
  102. Directory conventions follow the official [Codex](https://learn.chatgpt.com/docs/build-skills), [Claude Code](https://code.claude.com/docs/en/skills), and [Cursor](https://cursor.com/docs/skills) documentation.
  103. ## Example tasks
  104. **Audit**
  105. ```text
  106. Use code-audit to review the authentication flow. Report evidence, severity, impact, and recommended fixes. Do not change code.
  107. ```
  108. **Implement**
  109. ```text
  110. Use solid-engineering to add pagination to the orders endpoint. Preserve its documented response contract and verify the affected application flow.
  111. ```
  112. **Refactor**
  113. ```text
  114. Use refactoring to reduce coupling in the billing module. Preserve behavior, avoid unrelated rewrites, and run relevant regression checks.
  115. ```
  116. ## Updating and removing
  117. Existing destinations are **never overwritten**, including empty directories. There is no force, update, or uninstall command.
  118. To update, back up and move the installed folders for the skills you want to update outside the agent's discovery directories, then install the desired version. Keep the backup until you have reviewed the new instructions and restored intentional customizations. Updating the npm package alone does not update a previously copied skill.
  119. To remove a skill, delete only its installed directory and reload your agent session. Leave sibling skills and the parent directory intact.
  120. To add the new skills alongside an existing `solid-engineering` installation, select only the missing skills:
  121. ```sh
  122. npx @aaramsyy/solidengineering install --skill refactoring --skill code-audit
  123. ```
  124. Use the same `--agent` and scope as your existing installation. Before copying, the installer checks every selected destination. A known conflict stops the whole request without writing skills. An unexpected copy error can still leave earlier skills installed; inspect the reported paths before retrying.
  125. ## Troubleshooting
  126. | Symptom | What to check |
  127. | --- | --- |
  128. | `Destination already exists` | Back up and move the existing skill before reinstalling, or choose another `--dir`. |
  129. | `Installation incomplete` | Inspect the reported destination and filesystem permissions. A failed copy can leave partial files; move that partial directory before retrying. |
  130. | Skill does not appear | Check the target directory, agent configuration, and local skill support; reload the session. |
  131. | Runtime or syntax error | Check `node --version`; Node.js 22+ is required. |
  132. | Unknown option or missing value | Check the CLI reference and provide option values as separate arguments. |
  133. | npm authentication/download error | Check registry connectivity and npm configuration. A download failure occurs before the skill installer runs. |
  134. Report reproducible problems through [GitHub Issues](https://github.com/ramsyparker/solid-engineering/issues). Include OS, Node.js version, package version, command, and sanitized error output. Do not include credentials, tokens, or private project data.
  135. ## Install from a GitHub Release
  136. Download `aaramsyy-solidengineering-0.2.0.tgz` from [GitHub Releases](https://github.com/ramsyparker/solid-engineering/releases/tag/v0.2.0). This archive includes the installer, all three skills, README, and MIT license.
  137. From your project directory, substitute the path to your downloaded archive:
  138. ```sh
  139. npm exec --yes --package="/path/to/aaramsyy-solidengineering-0.2.0.tgz" -- solidengineering install
  140. ```
  141. For example, in Windows PowerShell:
  142. ```powershell
  143. npm exec --yes --package="C:/Users/YourName/Downloads/aaramsyy-solidengineering-0.2.0.tgz" -- solidengineering install --agent codex
  144. ```
  145. You can also install directly from the release asset:
  146. ```sh
  147. npx --yes https://github.com/ramsyparker/solid-engineering/releases/download/v0.2.0/aaramsyy-solidengineering-0.2.0.tgz install
  148. ```
  149. Add `--agent claude` or `--agent cursor` to select another agent. Back up and move any existing installation before reinstalling.
  150. With npm 12+, direct URL installs require an explicit per-command opt-in. If you see `EALLOWREMOTE`, use the downloaded archive as shown above, or run:
  151. ```sh
  152. npx --yes --allow-remote=root https://github.com/ramsyparker/solid-engineering/releases/download/v0.2.0/aaramsyy-solidengineering-0.2.0.tgz install
  153. ```
  154. GitHub Release **v0.2.0** includes all three skills and selective installation. The npm commands above use the version available on npm; publishing a GitHub Release does not update that registry.
  155. ## License
  156. [MIT](LICENSE). Copyright (c) 2026 **aaramsyy**.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.