eliptikwu
Claude Code skills by EliptikWu.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/eliptikwu--engineering-docs)HTML
<a href="/listings/eliptikwu--engineering-docs"><img src="/api/listings/eliptikwu--engineering-docs/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**Claude Code, as a plugin:**
/plugin marketplace add EliptikWu/engineering-docs /plugin install engineering-docs@eliptikwu
Or copy `skills/engineering-docs/` to `~/.claude/skills/engineering-docs/` (every project) or to `<repo>/.claude/skills/engineering-docs/` (one project).
**Other tools:** copy `skills/engineering-docs/` to `<repo>/.agents/skills/engineering-docs/` for one project, or to `~/.agents/skills/engineering-docs/` for all of them. Then ask for it in plain words ("set up the engineering docs", "audit the docs"), or invoke it by name where your tool supports that (`/engineering-docs`, `$engineering-docs` in Codex).
The project's instructions file can be whatever your tool reads (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`…); the template is named `CLAUDE.md`, rename it as needed.
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.
.claude-plugin/marketplace.json · Manifest · 16 lines
- {
- "name": "eliptikwu",
- "description": "Claude Code skills by EliptikWu.",
- "owner": {
- "name": "EliptikWu"
- },
- "plugins": [
- {
- "name": "engineering-docs",
- "source": "./",
- "description": "A small, fixed set of numbered engineering docs (01-10) shaped by your business model, with a backlog /next-task can consume and a coherence checker.",
- "version": "1.0.0",
- "license": "Apache-2.0"
- }
- ]
- }
README.md · README · 165 lines
- # engineering-docs
- [Leer en español](README.es.md)
- An agent skill that sets up and maintains a project's **engineering documentation**: a
- small, fixed set of numbered documents that rule over the code. The agent reads them
- before touching anything, and every behavior change updates them in the same pull request.
- It uses the open [Agent Skills](https://agentskills.io) format, so it runs in Claude Code,
- Codex, Gemini CLI, GitHub Copilot, Cursor and Devin Desktop.
- The method was battle-tested on three production projects (an internal CRM, a paid SaaS,
- and a standards-regulated app) before being written down as a skill. What the skill brings
- is **the method, not the content**: the content comes from a short interview and from your
- code. It never copies another project's docs.
- ## What you get
- ```
- CLAUDE.md short; read every session: rules, commands, "if you touch X, read Y"
- docs/
- README.md status line, "What's left" (the backlog), document index, open decisions
- 01-scope-and-definitions.md problem, roles, scope by phase, glossary
- 02-requirements.md RF-AAA-NN / RNF-AAA-NN, each with a WHEN … THE SYSTEM … scenario
- 03-architecture.md components, stack, permissions, decision log (ADR-NN)
- 04-database.md only if there's a database
- 05-ui-ux.md only if there's an interface
- 06-quality.md prioritized quality attributes, definition of done
- 07-optimizations.md only if there's a per-use cost (AI, paid APIs)
- 08-methodology.md iteration cycle, branches, phases, deployment
- 09-testing-qa.md only with personal data, multi-tenancy, payments or e2e flows
- 10-bug-fixing.md severity, the sweep, findings register (EV-NN), risks and debt
- history/ closed items, so live documents stay short
- ```
- The numbering is fixed: "doc 05" means the same thing in every project, even when it
- doesn't exist. The documents are written in your project's language (the templates are in
- English and their headings get translated); identifiers stay in English.
- ## Three modes
- | Mode | When | What it does |
- |---|---|---|
- | **New** | Empty or nearly empty repository | Interview → profile → documents from the templates |
- | **Adopt** | There's code but no docs (or different ones) | Reads the code first and only asks what the code can't say. Requirements describe what exists (`Status`, `Where`), and Phase 0 is an assessment that opens findings. The code rules are extracted from the code: only what repeats in three or more places, each citing an example file |
- | **Audit** | The project already uses the method | Runs the coherence checker (with `--paths` and `--traceability`) plus a "what rots" checklist, and proposes fixes instead of rewriting |
- ## It adapts to the business model
- Before writing anything it asks up to two rounds of questions: who pays, whether it
- charges inside the product, whether a standard or law governs it, personal data,
- multi-tenancy, surfaces (web, mobile, AI with per-use cost, public user docs), team and deployment,
- maturity. Each answer turns a **module** on or off
- ([`references/profiles.md`](skills/engineering-docs/references/profiles.md)):
- - **Payments:** "money correctness" becomes quality attribute #2, webhook rules go into
- CLAUDE.md, there's a Money domain in the database doc, and "charged without granting"
- is a critical bug.
- - **Regulated (ISO, data protection…):** "fidelity to the standard" goes to the top,
- requirements cite their clause in a `Source` column, and done means "checked against the
- text of the standard".
- - **Personal data / multi-tenant:** privacy requirements, a sensitive-data section, and a
- mandatory test with two users or two organizations.
- - **User documentation and runbooks:** each page is one Diátaxis type (tutorial, how-to,
- reference or explanation), and a user-visible change updates its page in the same PR.
- - **Interface, AI cost, own database, deployment, team size:** turn on 05, 07, 04,
- runbooks, or a role table, as needed.
- You see the resulting profile (5–10 lines) before anything is generated. What the
- interview can't answer becomes `TBD (who)` plus an open decision `D<n>`; nothing is
- invented.
- ## The coherence checker
- `scripts/coherence.py` is a stdlib-only Python script that checks, without changing
- anything:
- - duplicate IDs;
- - IDs cited but never defined;
- - a broken `Superseded by ADR-NN`;
- - links to documents that don't exist;
- - a README status date older than the latest date the README mentions;
- - unfilled template placeholders;
- - documents that have grown too long;
- - optionally, `Done` requirements that no code or test cites (`--traceability`);
- - optionally, code paths the docs name in backticks that don't exist (`--paths`);
- - optionally, IDs cited in a PR or commit message that don't exist (`--citations`).
- It understands English and Spanish keywords.
- ```bash
- python skills/engineering-docs/scripts/coherence.py /path/to/project [--traceability] [--paths]
- git log origin/main..HEAD --format=%B | python skills/engineering-docs/scripts/coherence.py . --citations -
- python -m unittest discover -s tests -v # the checker's own tests
- ```
- ## Works with next-task
- The backlog lives in one place: "What's left" in `docs/README.md`, with a table of
- batches, their dependencies and their appetite (a cap in PRs or sessions, from Shape Up:
- when it's spent, the batch is re-cut instead of dragging on). `CLAUDE.md` gets the line
- `Backlog: docs/README.md ("What's left")`, which is how
- [next-task](https://github.com/EliptikWu/next-task) finds the next item. Use this skill to
- lay the docs down and keep them honest, and next-task to work through the backlog one task
- per session.
- ## What it borrows, and what it leaves out
- It borrows from:
- - **Spec Kit:** a short set of non-negotiable project rules read before every change
- (here, `CLAUDE.md`). And a requirement exists before its code: an ID in 02 before
- implementation.
- - **Kiro:** EARS-style acceptance criteria. Every requirement has a verifiable
- `WHEN <situation> THE SYSTEM <result>` scenario, and the test that covers it cites the
- ID. Always-loaded steering becomes the "if you're going to touch X, read Y" table.
- - **BMAD:** discovery before planning (the interview), and scale-adaptive tracks. A small
- fix only touches its finding, while a new feature gets an ID, an ADR and scenarios.
- - **OpenSpec:** changes expressed as deltas. Every PR carries a "Documentation" section
- listing the requirements added, changed or removed and the ADRs added or superseded.
- - **Taskmaster:** tasks with dependencies. The next task is the first batch that isn't
- done and whose dependencies are.
- - **arc42:** the architecture skeleton: context, building blocks, deployment, decisions,
- prioritized quality attributes, risks and technical debt, glossary.
- It leaves out (see "What we left out" in
- [`references/rules.md`](skills/engineering-docs/references/rules.md)):
- - **A spec folder per feature.** It's written for one branch and then nobody maintains it.
- Requirements live in one living document.
- - **A separate `tasks.json` or task plan.** That's a second source of truth that drifts
- from the backlog.
- - **Agent personas (PM, architect…).** They're ceremony; skills and subagents are enough.
- - **The spec as the only source, with generated code.** Generation isn't deterministic.
- - **Giant instruction files.** Context rots, so `CLAUDE.md` stays short and the rest is
- read on demand.
- There's no benchmark for this skill: we haven't measured it, so we don't claim numbers.
- ## Install
- **Claude Code, as a plugin:**
- ```
- /plugin marketplace add EliptikWu/engineering-docs
- /plugin install engineering-docs@eliptikwu
- ```
- Or copy `skills/engineering-docs/` to `~/.claude/skills/engineering-docs/` (every project)
- or to `<repo>/.claude/skills/engineering-docs/` (one project).
- **Other tools:** copy `skills/engineering-docs/` to `<repo>/.agents/skills/engineering-docs/`
- for one project, or to `~/.agents/skills/engineering-docs/` for all of them. Then ask for
- it in plain words ("set up the engineering docs", "audit the docs"), or invoke it by name
- where your tool supports that (`/engineering-docs`, `$engineering-docs` in Codex).
- The project's instructions file can be whatever your tool reads (`CLAUDE.md`, `AGENTS.md`,
- `GEMINI.md`…); the template is named `CLAUDE.md`, rename it as needed.
- ## License
- [Apache 2.0](LICENSE). You can use, change and share it. Copies and derived works must
- keep the copyright and the [NOTICE](NOTICE) file, and must say what was changed. The
- license doesn't grant use of the author's name to promote a derived work.
- Made by [EliptikWu](https://github.com/EliptikWu).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.