@smitdev/ai-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smitdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @smitdev/ai-skills
+
+Reusable AI assistant **skills** you can install with one command — for
+**Claude Code**, **GitHub Copilot**, **Cursor**, and **Windsurf**.
+
+Skills are authored once in the Claude [Agent Skill](https://docs.claude.com/en/docs/claude-code/skills)
+format (`SKILL.md`) and converted on install to whatever your assistant expects.
+
+## Install a skill
+
+No global install needed — run it with `npx`:
+
+```bash
+# See what's available
+npx @smitdev/ai-skills list
+
+# Interactive: pick assistant(s) and skill(s)
+npx @smitdev/ai-skills install
+
+# Non-interactive examples
+npx @smitdev/ai-skills install --assistant claude --global
+npx @smitdev/ai-skills install --assistant copilot,cursor,windsurf
+npx @smitdev/ai-skills install --assistant all --skill contract --project
+```
+
+### Where files go
+
+| Assistant       | Scope            | Destination |
+|-----------------|------------------|-------------|
+| Claude Code     | `--global`       | `~/.claude/skills/<name>/SKILL.md` |
+| Claude Code     | `--project`      | `./.claude/skills/<name>/SKILL.md` |
+| GitHub Copilot  | project          | `./.github/instructions/<name>.instructions.md` |
+| Cursor          | project          | `./.cursor/rules/<name>.mdc` |
+| Windsurf        | project          | `./.windsurf/rules/<name>.md` |
+
+Copilot, Cursor, and Windsurf read their rules from inside a repo, so those
+always install into a project directory (`--dir`, default: current folder).
+Claude Code can install globally (available everywhere) or per-project.
+
+Use `--dry-run` to preview without writing anything.
+
+## Available skills
+
+- **contract** — Create a build-ready spec / PRD for a feature before any code
+  is written, so a coding assistant can build it without guessing.
+
+## Authoring your own skills
+
+Each skill is a folder under [`skills/`](skills/) containing a `SKILL.md` with
+YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: When to use this skill, in one or two sentences. The assistant uses this to decide when to apply it.
+---
+
+# My Skill
+
+Instructions for the assistant…
+```
+
+Drop the folder in `skills/`, bump the version, and publish. Any extra files in
+the folder are copied verbatim for Claude Code.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+'use strict';
+
+const readline = require('readline');
+const path = require('path');
+const { listSkills } = require('../lib/skills');
+const { adapters } = require('../lib/adapters');
+const { install } = require('../lib/install');
+
+const ASSISTANT_IDS = Object.keys(adapters);
+
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        args.flags[key] = true;
+      } else {
+        args.flags[key] = next;
+        i++;
+      }
+    } else if (a === '-y') {
+      args.flags.yes = true;
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function ask(rl, question) {
+  return new Promise((resolve) => rl.question(question, (a) => resolve(a.trim())));
+}
+
+function parseList(val, valid) {
+  if (val === true || !val) return [];
+  const items = String(val)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (val === 'all' || items.includes('all')) return valid.slice();
+  return items;
+}
+
+function printHelp() {
+  console.log(`
+ai-skills — install reusable AI assistant skills
+
+Usage:
+  npx @smitdev/ai-skills <command> [options]
+
+Commands:
+  list                 List the skills bundled in this package
+  install              Install skills for one or more assistants
+
+Options for "install":
+  --assistant <ids>    Comma-separated: ${ASSISTANT_IDS.join(', ')} (or "all")
+  --skill <names>      Comma-separated skill names (or "all"; default: all)
+  --global             Install to your home dir (Claude Code only)
+  --project            Install into a project (default)
+  --dir <path>         Project directory (default: current directory)
+  --dry-run            Show what would change without writing
+  -y, --yes            Skip interactive prompts (use flags / defaults)
+  -h, --help           Show this help
+
+Examples:
+  npx @smitdev/ai-skills list
+  npx @smitdev/ai-skills install --assistant claude --global
+  npx @smitdev/ai-skills install --assistant copilot,cursor --skill contract
+`);
+}
+
+async function pickFromList(rl, label, options) {
+  console.log(`\n${label}`);
+  options.forEach((o, i) => console.log(`  ${i + 1}. ${o.label}`));
+  console.log(`  (comma-separated numbers, or "a" for all)`);
+  const ans = await ask(rl, '> ');
+  if (ans.toLowerCase() === 'a' || ans === '') return options.map((o) => o.id);
+  const picked = ans
+    .split(',')
+    .map((s) => parseInt(s.trim(), 10))
+    .filter((n) => n >= 1 && n <= options.length)
+    .map((n) => options[n - 1].id);
+  return [...new Set(picked)];
+}
+
+async function runInstall(args) {
+  const skills = listSkills();
+  if (skills.length === 0) {
+    console.error('No skills found in this package.');
+    process.exit(1);
+  }
+
+  const projectDir = path.resolve(
+    typeof args.flags.dir === 'string' ? args.flags.dir : process.cwd()
+  );
+  const dryRun = !!args.flags['dry-run'];
+  const scope = args.flags.global ? 'global' : 'project';
+
+  let assistants = parseList(args.flags.assistant, ASSISTANT_IDS);
+  let skillNames = parseList(args.flags.skill, skills.map((s) => s.name));
+
+  const nonInteractive =
+    args.flags.yes || (assistants.length > 0);
+
+  if (!nonInteractive && process.stdin.isTTY) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    if (assistants.length === 0) {
+      assistants = await pickFromList(
+        rl,
+        'Which assistant(s)?',
+        ASSISTANT_IDS.map((id) => ({ id, label: adapters[id].label }))
+      );
+    }
+    if (skillNames.length === 0) {
+      skillNames = await pickFromList(
+        rl,
+        'Which skill(s)?',
+        skills.map((s) => ({ id: s.name, label: `${s.name} — ${truncate(s.description, 60)}` }))
+      );
+    }
+    rl.close();
+  }
+
+  if (assistants.length === 0) assistants = ASSISTANT_IDS.slice();
+  if (skillNames.length === 0) skillNames = skills.map((s) => s.name);
+
+  const invalidA = assistants.filter((a) => !ASSISTANT_IDS.includes(a));
+  if (invalidA.length) {
+    console.error(`Unknown assistant(s): ${invalidA.join(', ')}`);
+    console.error(`Valid: ${ASSISTANT_IDS.join(', ')}`);
+    process.exit(1);
+  }
+  const selectedSkills = skills.filter((s) => skillNames.includes(s.name));
+  const invalidS = skillNames.filter((n) => !skills.some((s) => s.name === n));
+  if (invalidS.length) {
+    console.error(`Unknown skill(s): ${invalidS.join(', ')}`);
+    console.error(`Valid: ${skills.map((s) => s.name).join(', ')}`);
+    process.exit(1);
+  }
+
+  const results = install({
+    assistants,
+    skills: selectedSkills,
+    scope,
+    projectDir,
+    dryRun,
+  });
+
+  const verb = dryRun ? 'Would install' : 'Installed';
+  console.log(`\n${verb} ${selectedSkills.length} skill(s) for ${assistants.length} assistant(s):\n`);
+  for (const r of results) {
+    console.log(`  [${r.assistant}] ${r.skill}  ->  ${r.path}  (${r.action})`);
+  }
+  if (dryRun) console.log('\n(dry run — no files were written)');
+}
+
+function truncate(s, n) {
+  s = String(s || '');
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+
+  if (args.flags.help || args.flags.h || cmd === 'help' || !cmd) {
+    printHelp();
+    return;
+  }
+
+  if (cmd === 'list') {
+    const skills = listSkills();
+    console.log(`\n${skills.length} skill(s) available:\n`);
+    for (const s of skills) {
+      console.log(`  ${s.name}`);
+      console.log(`    ${truncate(s.description, 100)}\n`);
+    }
+    return;
+  }
+
+  if (cmd === 'install') {
+    await runInstall(args);
+    return;
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  printHelp();
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/lib/adapters.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+/**
+ * Each adapter turns a parsed skill into one or more output targets:
+ *   { path, content }      -> write a single file
+ *   { path, copyDir }      -> recursively copy a source folder (native format)
+ *
+ * `scope` is 'global' (user home), 'project' (a repo), or 'both'.
+ */
+
+// YAML-safe scalar: JSON double-quoted strings are valid YAML double-quoted
+// scalars, so this handles colons, quotes, and apostrophes in descriptions.
+function yamlString(s) {
+  return JSON.stringify(String(s == null ? '' : s));
+}
+
+const claude = {
+  id: 'claude',
+  label: 'Claude Code',
+  scope: 'both',
+  // Native format — copy the whole skill folder verbatim.
+  resolve(skill, { scope, projectDir }) {
+    const base =
+      scope === 'global'
+        ? path.join(os.homedir(), '.claude', 'skills')
+        : path.join(projectDir, '.claude', 'skills');
+    return [{ path: path.join(base, skill.name), copyDir: skill.dir }];
+  },
+};
+
+const copilot = {
+  id: 'copilot',
+  label: 'GitHub Copilot',
+  scope: 'project',
+  resolve(skill, { projectDir }) {
+    const content =
+      `---\n` +
+      `description: ${yamlString(skill.description)}\n` +
+      `applyTo: "**"\n` +
+      `---\n\n` +
+      skill.body;
+    return [
+      {
+        path: path.join(
+          projectDir,
+          '.github',
+          'instructions',
+          `${skill.name}.instructions.md`
+        ),
+        content,
+      },
+    ];
+  },
+};
+
+const cursor = {
+  id: 'cursor',
+  label: 'Cursor',
+  scope: 'project',
+  resolve(skill, { projectDir }) {
+    const content =
+      `---\n` +
+      `description: ${yamlString(skill.description)}\n` +
+      `globs:\n` +
+      `alwaysApply: false\n` +
+      `---\n\n` +
+      skill.body;
+    return [
+      {
+        path: path.join(projectDir, '.cursor', 'rules', `${skill.name}.mdc`),
+        content,
+      },
+    ];
+  },
+};
+
+const windsurf = {
+  id: 'windsurf',
+  label: 'Windsurf',
+  scope: 'project',
+  resolve(skill, { projectDir }) {
+    const content =
+      `---\n` +
+      `trigger: model_decision\n` +
+      `description: ${yamlString(skill.description)}\n` +
+      `---\n\n` +
+      skill.body;
+    return [
+      {
+        path: path.join(projectDir, '.windsurf', 'rules', `${skill.name}.md`),
+        content,
+      },
+    ];
+  },
+};
+
+const adapters = { claude, copilot, cursor, windsurf };
+
+module.exports = { adapters, yamlString };

package/lib/install.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { adapters } = require('./adapters');
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+function writeFile(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+/**
+ * Install the given skills for the given assistants.
+ * opts: { assistants: string[], skills: Skill[], scope, projectDir, dryRun }
+ * Returns a list of { assistant, skill, path, action } records.
+ */
+function install({ assistants, skills, scope, projectDir, dryRun }) {
+  const results = [];
+  for (const id of assistants) {
+    const adapter = adapters[id];
+    if (!adapter) throw new Error(`Unknown assistant: ${id}`);
+
+    // Project-only adapters ignore a 'global' scope request.
+    const effScope = adapter.scope === 'project' ? 'project' : scope;
+
+    for (const skill of skills) {
+      const targets = adapter.resolve(skill, { scope: effScope, projectDir });
+      for (const t of targets) {
+        const existed = fs.existsSync(t.path);
+        if (!dryRun) {
+          if (t.copyDir) copyDir(t.copyDir, t.path);
+          else writeFile(t.path, t.content);
+        }
+        results.push({
+          assistant: adapter.label,
+          skill: skill.name,
+          path: t.path,
+          action: existed ? 'updated' : 'created',
+        });
+      }
+    }
+  }
+  return results;
+}
+
+module.exports = { install, copyDir };

package/lib/skills.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SKILLS_DIR = path.join(__dirname, '..', 'skills');
+
+/**
+ * Minimal YAML frontmatter parser. Handles the flat `key: value` pairs we use
+ * in SKILL.md (name, description). Values run to end of line; surrounding
+ * quotes are stripped. This is intentionally tiny so the installer ships with
+ * zero dependencies.
+ */
+function parseFrontmatter(raw) {
+  const fm = {};
+  const lines = raw.split(/\r?\n/);
+  let key = null;
+  for (const line of lines) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s?(.*)$/);
+    if (m) {
+      key = m[1];
+      fm[key] = stripQuotes(m[2].trim());
+    } else if (key && /^\s+\S/.test(line)) {
+      // continuation line for a folded value
+      fm[key] = (fm[key] + ' ' + line.trim()).trim();
+    }
+  }
+  return fm;
+}
+
+function stripQuotes(v) {
+  if (
+    (v.startsWith('"') && v.endsWith('"')) ||
+    (v.startsWith("'") && v.endsWith("'"))
+  ) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+/**
+ * Parse a single skill folder into { name, description, body, dir }.
+ * Only the FIRST frontmatter block (the top of SKILL.md) is stripped — any
+ * `---` inside fenced code blocks in the body is preserved.
+ */
+function parseSkill(dir) {
+  const file = path.join(dir, 'SKILL.md');
+  const md = fs.readFileSync(file, 'utf8');
+  const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  let fm = {};
+  let body = md;
+  if (m) {
+    fm = parseFrontmatter(m[1]);
+    body = md.slice(m[0].length);
+  }
+  return {
+    name: fm.name || path.basename(dir),
+    description: fm.description || '',
+    body: body.replace(/^\s+/, ''),
+    dir,
+  };
+}
+
+/** Discover every skill folder under skills/. */
+function listSkills() {
+  if (!fs.existsSync(SKILLS_DIR)) return [];
+  return fs
+    .readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .filter((d) => fs.existsSync(path.join(SKILLS_DIR, d.name, 'SKILL.md')))
+    .map((d) => parseSkill(path.join(SKILLS_DIR, d.name)))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+module.exports = { listSkills, parseSkill, parseFrontmatter, SKILLS_DIR };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@smitdev/ai-skills",
+  "version": "0.1.0",
+  "description": "Install reusable AI assistant skills (Claude Code, GitHub Copilot, Cursor, Windsurf) with one command.",
+  "bin": {
+    "ai-skills": "bin/cli.js"
+  },
+  "type": "commonjs",
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "copilot",
+    "cursor",
+    "windsurf",
+    "ai",
+    "skills",
+    "agent",
+    "prompt"
+  ],
+  "author": "smitdev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smitcode/ai-skills.git"
+  },
+  "homepage": "https://github.com/smitcode/ai-skills#readme",
+  "bugs": {
+    "url": "https://github.com/smitcode/ai-skills/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/contract/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: contract
+description: Create a contract - a spec or PRD that fully explains a feature before any code is written, so a coding assistant or engineer can build it without guessing. Use this whenever the user wants to plan or spec a feature before building - things like "spec this out", "write a PRD", "let's plan this feature first", "make an implementation doc", "write the contract for X", or "I want a plan before we touch the code". Trigger it even if the user doesn't say the word "contract" - any time they want a build-ready description of a feature instead of the code itself.
+---
+
+# Contract
+
+A contract is a plan that you and the user agree on before any code is written. It is the one document a coding assistant reads to build the feature without guessing or making things up. Your job here is to make that document - not to write the feature code.
+
+Do these three steps in order: understand the codebase, then ask the user questions, then write the contract. Don't jump straight to writing - a contract built on guesses is worse than no contract.
+
+## Step 1 - Understand the codebase
+
+Before you ask the user anything, read the parts of the codebase the feature will touch. You want real files, not a vague idea of the project.
+
+Find and read the files that will likely change, or that the new code has to work with. For each one, note what it does now, the patterns it follows (naming, error handling, how state and APIs are done), and where the new feature would fit in.
+
+By the end of this step you should have a short list of real file paths, what each one does today, and where the new feature connects. You'll use this directly in the contract, so write down the real paths - never write a spec that isn't connected to the real code.
+
+## Step 2 - Ask the user questions
+
+Now fill in the gaps. The user knows what they want; you know the code. The questions bring the two together and find the decisions that shape the design.
+
+Ask one question at a time - never a big list at once. After each answer, ask the next one. This keeps it easy for the user and lets each answer guide the next question.
+
+For each question, give a short list of simple answer options to pick from, not an open question. Keep the options non-technical - describe what happens, not how it's built. Mark the option you recommend and say in one line why you'd pick it, then ask if they're okay with it. Always add an "other - let me explain" option so they're not stuck with your choices.
+
+Across the questions, cover: what the feature should do for the user, what's not included (the limits of the work), edge cases and error states, and any spot where two reasonable choices exist. Stop once you can explain the whole feature start to finish with no "it depends" left.
+
+**Example of how a question should look:**
+
+> When a search returns no results, what should the user see?
+>
+> - **A - A short "nothing found" message** (recommended: simplest, and it matches how the rest of the app handles empty states)
+> - **B - The empty state plus a few suggestions on what to try next**
+> - **C - Keep the last results on screen and just show a small note**
+> - **D - Something else - tell me what you have in mind**
+>
+> I'd go with A. Want to go with that, or pick another?
+
+## Step 3 - Check, then write the contract
+
+Before you write the full document, say your understanding back in a few sentences and get a yes. This is a cheap way to avoid writing a long doc based on a wrong idea.
+
+Then write the contract using the template below. Leave out any section that doesn't apply (for example, no "Data model" section for a simple styling change) instead of filling it with fluff - but keep the numbers on the sections you do use. Write it so that an engineer or coding assistant who never saw the conversation could build the feature correctly from this document alone.
+
+### Contract template
+
+```markdown
+# Contract: <Feature name>
+
+**Status:** Draft
+**Date:** <YYYY-MM-DD>
+**Area:** <which part of the product / module>
+
+## 1. Summary
+
+One short paragraph, plain words: what we're building and why.
+
+## 2. Problem
+
+The problem this solves. What happens now and why that's not good enough.
+
+## 3. Goals
+
+Clear bullets - what success looks like.
+
+## 4. Not included (out of scope)
+
+What this feature does NOT do. This is just as important as the goals - it
+stops a coding assistant from adding extra work or features no one asked for.
+
+## 5. The code today (what's there now)
+
+The real files involved and what they do now:
+
+- `path/to/file.ts` - what it does today; what changes here
+- `path/to/other.py` - ...
+  Patterns and conventions the new code should follow.
+
+## 6. The plan
+
+The approach in a sentence or two, then broken down:
+
+### 6.1 UI and UX
+
+What the user sees and does. Every state: normal, loading, empty, error,
+success. Note accessibility where it matters.
+
+### 6.2 Data model
+
+New or changed data: entities, fields, types, how they relate. (Skip if none.)
+
+### 6.3 API / interface
+
+For each endpoint or function: the signature or method + path, what goes in,
+what comes back, and the error cases. For frontend: component props, events,
+and the state it gives back.
+
+### 6.4 Logic and edge cases
+
+The step-by-step behavior. List the edge cases and say how each is handled -
+this is where most of the confusion hides.
+
+## 7. Performance and optimization
+
+How fast and how cheap this has to be, made concrete (real numbers where you
+can). Cover what applies:
+
+- Expected load / scale - how many requests, rows, items, or users, etc.
+- The hot paths - the parts that run a lot or work on big data, and the target
+  (e.g. "the list should load in under X seconds with 10,000 rows").
+- Caching, batching, rate limits, concurrency - what to reuse or throttle.
+- Cost - any API quota or money limits, and how to stay under them.
+  Skip this only if the feature has no real performance concern.
+
+## 8. Other requirements
+
+Only the ones that apply: security and access, logging/monitoring, easy to
+maintain, reusable.
+
+## 9. Files to change (checklist)
+
+A checklist the coding assistant can follow:
+
+- [ ] `path/to/file.ts` - what to change
+- [ ] `path/to/new_file.py` - new; what it holds
+
+## 10. Done when (acceptance criteria)
+
+How we know it's done, written as things you can test:
+
+- Given <situation>, when <action>, then <result>.
+
+## 11. Risks and open questions
+
+Guesses you made, choices left for later, anything still unclear.
+```
+
+## Where to save it
+
+Save the contract as a Markdown file. Use the project's existing folder if there is one - look for a `specs/`, `contracts/`, `docs/specs/`, or `.specify/` folder and put it there. If there isn't one, make a `specs/` folder.
+
+Name the file after the feature, in kebab-case: `specs/<feature-slug>.md` (for example `specs/user-profile-page.md`). Tell the user the path when you're done.
+
+## Rules to keep in mind
+
+- Make the contract, not the code. If the user also wants the code, finish and confirm the contract first - that's the thing they'll read and reuse.
+- Keep the user-facing parts (Summary, Problem, Goals) in plain words, and the build-facing parts (API, done-when) exact. The coding assistant needs the exact parts to be exact.
+- If you hit a decision while writing that you didn't settle in the questions, stop and ask instead of guessing - then write the answer into the doc.