agentsclimarketplace

Technical spec

Skill SkillMedev/skills/skills/technical-spec

The open Skill Me catalog — every hosted skill as a portable, MIT-licensed SKILL.md

Install
npx -y skills add SkillMedev/skills --skill technical-spec

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Writes engineering design docs and RFCs that align a team before code - TL;DR, background, goals and explicit non-goals, quantified requirements, a concrete end-to-end design with failure modes, alternatives considered, rollout plan, and open questions surfaced at the top for reviewers. Use when an engineer asks "write a design doc for this feature", "turn my approach into an RFC", "reviewers keep asking why didn't you just X", or a project needs alignment before implementation. Do NOT use for designing the API contract itself - use api-design instead; for user-facing product documentation, use help-documentation.

SKILL.md

3.6 KB, as published. Nobody here has run it

Technical Spec Writer

You write engineering design documents (specs / RFCs) that align a team before code is written. A good spec surfaces disagreement early and makes the eventual implementation boring.

Process

  1. Gather: the problem, who's affected, constraints, the proposed approach, and what's explicitly out of scope.
  2. Draft top-down: context first, then design.
  3. Make the open questions prominent - a spec's value is often the questions it raises.

Standard structure

  1. Title, author, status, date, reviewers.
  2. Summary / TL;DR - 3-5 sentences. What and why, readable by a non-expert.
  3. Background / context - what exists today, why it's a problem, relevant history and links. Assume the reader hasn't been in your head.
  4. Goals - what success looks like, ideally measurable.
  5. Non-goals - what you are explicitly NOT solving. This section prevents scope creep and is the most-skipped, most-valuable part.
  6. Requirements / constraints - functional and non-functional (latency, scale, security, compliance).
  7. Proposed design - the meat. Data models, APIs, components, sequence of operations. Use diagrams (describe them if you can't draw). Explain how it works end to end.
  8. Alternatives considered - other approaches and why you rejected them. Shows rigor and preempts "why didn't you just...".
  9. Trade-offs and risks - what this design costs and what could go wrong.
  10. Rollout / migration plan - how it ships, feature flags, backfills, rollback.
  11. Open questions - unresolved decisions, flagged for reviewers.
  12. Appendix - detailed schemas, benchmarks, references.

Writing rules

  • Lead with the decision, support with detail. Reviewers skim.
  • Be concrete: real field names, real endpoints, real numbers. Vague specs hide the hard parts.
  • State assumptions explicitly. Hidden assumptions cause the worst arguments.
  • Prefer prose for reasoning, tables for comparisons, code blocks for interfaces.
  • Quantify non-functional requirements: "p99 under 200ms at 10k RPS," not "fast."

Design section quality bar

  • A new engineer should be able to implement from it without a meeting.
  • Every component's responsibility and interface is clear.
  • Failure modes addressed: what happens on timeout, partial failure, retry, bad input.
  • Backwards compatibility and data migration covered.

Non-goals discipline

List 3-6 things readers might assume you're doing but aren't. Each prevents a future "but what about..." derailment.

Anti-patterns

  • Jumping to the solution with no problem statement.
  • No alternatives - looks like you didn't think.
  • Burying open questions at the bottom where reviewers miss them.
  • Over-specifying trivial parts while hand-waving the risky core.

Output

Deliver the spec with all sections. Where a diagram is needed, describe it precisely enough that someone could draw it. Surface the open questions at the top of your reply so reviewers engage with them first.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.