Skip to content
Back to search

awesome-requirements-writer

Use when drafting, rewriting, reviewing, or decomposing technical product requirements for product systems, micro-processors, sensors, actuators, or functions, diagnostics, interfaces, or specifications, engineering change requests. Helps turn engineering know-how, notes, standards, customer notes and test expectations from conversational casual writing into clear, atomic, measurable, traceable,unambiguous requirements with acceptance criteria.

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/muchengracedriver--awesome-requirements-writer/badge.svg)](/listings/muchengracedriver--awesome-requirements-writer)

HTML

<a href="/listings/muchengracedriver--awesome-requirements-writer"><img src="/api/listings/muchengracedriver--awesome-requirements-writer/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.

These steps run a script from the network that findsafeskills does not scan.

**Method 1 (Recommended):** Tell your agent directly: install `awesome-requirements-writer` skill.

**Method 2:**

Prerequisite: install Node.js 18 or newer.

Install Node.js LTS on Linux/macOS with nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash && . "$HOME/.nvm/nvm.sh" && nvm install --lts

Check your environment:

node --version

After confirming Node.js is installed, run:

npx awesome-requirements-writer install

Note: This package also provides an optional installer CLI for target-specific adapters. For example, if you only want to install to the Codex-specific directory:

npx awesome-requirements-writer install codex

OpenClaw and Hermes both consume `SKILL.md`-style skill folders, so they reuse the same canonical skill package:

npx awesome-requirements-writer install openclaw
npx awesome-requirements-writer install hermes

List supported targets:

npx awesome-requirements-writer list

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.

SKILL.md · Manifest · 67 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: awesome-requirements-writer
  3. description: Use when drafting, rewriting, reviewing, or decomposing technical product requirements for product systems, micro-processors, sensors, actuators, or functions, diagnostics, interfaces, or specifications, engineering change requests. Helps turn engineering know-how, notes, standards, customer notes and test expectations from conversational casual writing into clear, atomic, measurable, traceable,unambiguous requirements with acceptance criteria.
  4. ---
  5. # Awesome Requirements Writer
  6. ## Overview
  7. Turn engineering intent into requirements that can be designed, reviewed, implemented, verified, and traced. Prefer precise requirements over broad product prose, and flag missing engineering inputs instead of inventing thresholds.
  8. ## Requirement Principles
  9. A strong requirement is:
  10. - **Clean and direct:** include only necessary normative or definitional content in the requirement statement, no rationale content.
  11. - **Unambiguous:** avoid subjective terms, vague modifiers, and implicit Boolean logic; use explicit `AND` / `OR` for compound conditions only; plain enumerations use plain "and" / "or" (Chinese 和 / 或).
  12. - **Atomic:** assign one requirement ID to one indivisible obligation, condition, or behavior.
  13. - **Positively defined:** describe when the system shall perform the required behavior; avoid defining behavior by negating the opposite condition.
  14. - **No magic numbers:** all static numbers shall be expressed by a static variable name with a table of all static variables with its real engineering value.
  15. - **Directly testable:** make required inputs controllable and required outputs observable by the intended verification method.
  16. - **Separate from information:** keep rationale, examples, diagrams, repeated context, and verification notes outside the normative requirement text.
  17. - **Traceable:** link upward to source, system, safety, customer, regulatory, or design-constraint needs, and sideways or downward to test and design evidence.
  18. ## Workflow
  19. 1. Identify the item under requirement: product system, subsystem, feature, variant, and lifecycle phase.
  20. 2. Extract stakeholder intent, system behavior, constraints, interfaces and validation expectations.
  21. 3. Determine if the content is "information" or "requirement". Information is the content which is rationale, examples, diagrams, repeated else-defined requirements, and verification notes outside the normative requirement text.
  22. 4. Classify requirements by type: functional vs non-functional.
  23. 5. Draft atomic "shall" statements with a single subject, condition, behavior, measurable target, operating bounds, and verification path.
  24. 6. Add metadata: type(information/requirement), ID , content body and acceptance criteria.
  25. 7. List all functional requirements and related information in one chapter, while all non-functional requirements in another.
  26. 8. In a new chapter make a table of all static variables and its value. If no value is given, type TBD.
  27. 9. Audit the result for ambiguity, hidden design decisions, unverifiable claims, duplicate requirements, conflicting limits, missing fault behavior, and missing open questions.
  28. **Note:** Functional requirements are direct related to a specific feature or design, while non-functional requirements are related to general performance, system efficiency, software extensibility etc。 They are not direct related to feature level performance definition,more focusing on system level or product level. For example, "The fault flag shall be set within 100 ms after the fault occurs" is a functional requirement, while "The CPU load of the product shall be equal or less than 80%" is a non-functional requirement.
  29. ## Requirement Shape
  30. Use this format unless the user asks for another one:
  31. for information:
  32. - [Info] `<information body>`
  33. for requirement:
  34. - [Req `<ID>`] `<requirement body>` | `<acceptance criteria>`
  35. ## Output Rules
  36. - Match the user's language. If the user writes in Chinese, draft requirements in Chinese unless they request English.
  37. - If source notes are incomplete, produce the best draft plus a short "Open Questions" list.
  38. - If multiple interpretations are plausible, state the assumption used.
  39. - Generate output as a .md file.
  40. ## Project-Specific Guidelines
  41. User can add their customized project-specific guidelines in this section.
  42. ## References
  43. - Read `references/requirement-patterns-en.md` when drafting many requirements or converting informal engineering notes in English.
  44. - Read `references/requirement-patterns-zh.md` when drafting many requirements or converting informal engineering notes in Chinese.
  45. - Read `references/automotive-context.md` when the work involves automotive engineering.
README.md · README · 161 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Awesome Requirements Writer
  2. v1.0.0
  3. [![npm version](https://img.shields.io/npm/v/awesome-requirements-writer?label=npm)](https://www.npmjs.com/package/awesome-requirements-writer)
  4. [![npm downloads](https://img.shields.io/npm/dm/awesome-requirements-writer?label=downloads)](https://www.npmjs.com/package/awesome-requirements-writer)
  5. 本skill支持中文技术需求文档编写,请浏览 简体中文(./README-zh.md) 内容。
  6. As an automotive engineer and techinical manager with more than ten years of experience who has led engineering teams through ASPICE certification, I summarized what I have learned from years of writing and reviewing technical product requirements into this reusable AI agent skill. It helps turn engineering notes, customer inputs, standards, and test expectations into clear, testable technical product requirements.
  7. Some of the ideas behind this skill are discussed in an article I wrote (in Chinese) a couple years ago: https://zhuanlan.zhihu.com/p/338598640
  8. English | [简体中文](./README-zh.md)
  9. ## Problems Addressed
  10. Junior engineers often run into recurring problems when writing technical requirements, such as:
  11. - Conversational engineering notes becoming vague requirements;
  12. - Requirement text mixing normative behavior with rationale, examples, diagrams, or test advice;
  13. - Compound conditions with unclear `AND` / `OR` logic;
  14. - One requirement ID covering multiple behaviors or multiple test points;
  15. - Static values written directly into requirements without named variables or a variable table;
  16. - Inputs, outputs, states, and acceptance criteria that are not testable;
  17. - Intermediate-level requirements that cannot be clearly linked to upper-level or lower-level requirements.
  18. ## Solution
  19. This repository packages one `SKILL.md` file plus English and Chinese requirement-writing templates as an AI-agent skill to help compensate for gaps in requirement-writing experience.
  20. | Principle | Prevents |
  21. | --- | --- |
  22. | **Clean and direct** | Rationale or background information leaking into normative requirement text |
  23. | **Unambiguous** | Subjective wording, hidden assumptions, unclear Boolean logic |
  24. | **Atomic** | One ID covering multiple obligations or conditions |
  25. | **Positively defined** | Requirements defined by negating the opposite condition |
  26. | **No magic numbers** | Hard-coded values without a static-variable table |
  27. | **Directly testable** | Inputs or outputs that verification teams cannot control or observe |
  28. | **Separate requirements from information** | Requirements, explanations, context, examples, and diagrams mixed together |
  29. | **Traceable** | Requirements without source, test, design, or acceptance links |
  30. ## Install
  31. **Method 1 (Recommended):**
  32. Tell your agent directly: install `awesome-requirements-writer` skill.
  33. **Method 2:**
  34. Prerequisite: install Node.js 18 or newer.
  35. Install Node.js LTS on Linux/macOS with nvm:
  36. ```bash
  37. curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash && . "$HOME/.nvm/nvm.sh" && nvm install --lts
  38. ```
  39. Check your environment:
  40. ```bash
  41. node --version
  42. ```
  43. After confirming Node.js is installed, run:
  44. ```bash
  45. npx awesome-requirements-writer install
  46. ```
  47. Note:
  48. This package also provides an optional installer CLI for target-specific adapters. For example, if you only want to install to the Codex-specific directory:
  49. ```bash
  50. npx awesome-requirements-writer install codex
  51. ```
  52. OpenClaw and Hermes both consume `SKILL.md`-style skill folders, so they reuse the same canonical skill package:
  53. ```bash
  54. npx awesome-requirements-writer install openclaw
  55. npx awesome-requirements-writer install hermes
  56. ```
  57. List supported targets:
  58. ```bash
  59. npx awesome-requirements-writer list
  60. ```
  61. ## Use
  62. Invoke the skill explicitly:
  63. ```text
  64. Use $awesome-requirements-writer to turn these engineering notes into product requirements:
  65. ...
  66. ```
  67. The skill follows the user's language. Chinese input produces Chinese requirements unless English is requested.
  68. ## Repository Layout
  69. ```text
  70. package.json
  71. bin/awesome-requirements-writer.js
  72. SKILL.md
  73. references/
  74. automotive-context.md
  75. requirement-patterns-en.md
  76. requirement-patterns-zh.md
  77. adapters/
  78. codex/
  79. claude/
  80. cursor/
  81. gemini/
  82. opencode/
  83. codebuddy/
  84. github-copilot/
  85. trae/
  86. ```
  87. `SKILL.md` is the core agent instruction. The files in `references/` are loaded only when the task needs detailed templates or automotive engineering context.
  88. OpenClaw and Hermes reuse the `SKILL.md` package rather than adding a separate adapter wrapper.
  89. ## Adapters
  90. | Target | Adapter source | Install target |
  91. | --- | --- | --- |
  92. | Shared Agent Skills | `adapters/codex/.agents/skills/awesome-requirements-writer/` | `~/.agents/skills/awesome-requirements-writer/` or project `.agents/skills/awesome-requirements-writer/` |
  93. | Codex-only | `adapters/codex/.agents/skills/awesome-requirements-writer/` | `~/.codex/skills/awesome-requirements-writer/` or project `.codex/skills/awesome-requirements-writer/` |
  94. | Claude Code | `adapters/claude/.claude/skills/awesome-requirements-writer/` | `.claude/skills/awesome-requirements-writer/` or `~/.claude/skills/awesome-requirements-writer/` |
  95. | Cursor | `adapters/cursor/.cursor/rules/` | `.cursor/rules/`, including `references/` |
  96. | Gemini CLI | `adapters/gemini/` | Merge into `GEMINI.md`; copy references under `.gemini/awesome-requirements-writer/` |
  97. | OpenCode | `adapters/opencode/` | Merge `AGENTS.snippet.md` into `AGENTS.md`; copy references under `.opencode/awesome-requirements-writer/` |
  98. | OpenClaw | `adapters/codex/.agents/skills/awesome-requirements-writer/` | `~/.openclaw/skills/awesome-requirements-writer/` or workspace `skills/awesome-requirements-writer/` |
  99. | Hermes Agent | `adapters/codex/.agents/skills/awesome-requirements-writer/` | `~/.hermes/skills/awesome-requirements-writer/` |
  100. | CodeBuddy | `adapters/codebuddy/.codebuddy/rules/awesome-requirements-writer/` | `.codebuddy/rules/awesome-requirements-writer/`, including `RULE.mdc` and `references/` |
  101. | GitHub Copilot | `adapters/github-copilot/.github/` | `.github/`, including `copilot-instructions.md`, `instructions/`, and `instructions/references/` |
  102. | Trae | `adapters/trae/.trae/` | Trae project rules path, confirm whether your version uses `.trae/project_rules.md` or `.trae/rules/project_rules.md` |
  103. Rule-style adapters include bundled `references/`, but their entry files explicitly tell the agent not to load every reference by default. The agent should read only the matching language or automotive-context reference when the task needs it. OpenClaw and Hermes use the canonical `SKILL.md` package directly instead of a separate wrapper file. OpenClaw/Hermes support means local SKILL.md-compatible installation support; it does not claim ClawHub or Hermes registry publication until those registry flows are tested separately. For fixed entry filenames such as `AGENTS.md` or `GEMINI.md`, merge the provided snippet into the user's existing file instead of overwriting it.
  104. The CLI installer performs this merge automatically by using a marked block. Re-running the installer updates that block instead of appending duplicates.
  105. ## How to Know It's Working
  106. The skill is working if the output has:
  107. - Requirements separated from explanatory information.
  108. - Stable IDs such as `SYS-001`, `SWE-001`, or `HW-001`.
  109. - Explicit triggers, states, inputs, outputs, and acceptance criteria.
  110. - Named static variables instead of unexplained numbers.
  111. - Clear `AND` / `OR` logic for compound conditions.
  112. - Open questions for missing engineering values instead of invented thresholds.
  113. ## Customization
  114. Users can edit `SKILL.md` to adjust the core behavior, and can add company- or team-specific rules under a `## Project-Specific Guidelines` section. Edit `references/requirement-patterns-en.md` and `references/requirement-patterns-zh.md` to adjust language-specific examples, templates, and terminology.
  115. ## License
  116. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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