# Deepseek Reason

> Reasoning completion against DeepSeek's `deepseek-reasoner` (R1), returning the chain of thought apart from the answer. Use when a task needs step-by-step reasoning from DeepSeek. Reads DEEPSEEK_API_KEY; returns status:degraded when unset or unreachable.

- Skill: `ruvnet/deepseek-reason` (Agent Skill)
- Install (CLI): `npx get-skill add ruvnet/deepseek-reason`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruvnet/deepseek-reason/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ruvnet (https://skillmd.com/u/ruvnet)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/ruvnet/deepseek-reason

---


Wraps DeepSeek's reasoning model so ruflo callers can get an explicit
chain-of-thought back with the final answer, without having to parse it
out of the message content. Same subprocess-invocation shape as the sibling
`deepseek-chat` skill.

## When to use

- Multi-step reasoning tasks: proofs, plans, root-cause analysis, hard
  bug triage.
- You want to *see* the model's thinking (for audit, for training data,
  or to sanity-check its final answer).
- You can tolerate the higher latency and token cost of a reasoner vs
  `deepseek-chat`.

## Data handling

The prompt and any `--system` text are sent over the network to `api.deepseek.com`, a third party. Do not put secrets, credentials, personal data or proprietary code you are not allowed to share into them. The API key is read from `DEEPSEEK_API_KEY` in your shell only; never paste it into a prompt, a file or a command line.

## Algorithm

Implementation: [`scripts/reason.mjs`](../../scripts/reason.mjs).

1. Read `DEEPSEEK_API_KEY` from env. Degrade gracefully when missing.
2. POST to `/v1/chat/completions` with `{ model: 'deepseek-reasoner', messages, max_tokens? }`.
   Per DeepSeek's docs, `temperature`/`top_p` are ignored for reasoner
   models — this script does not forward them.
3. Extract `choices[0].message.content` AND `choices[0].message.reasoning_content`.
4. JSON output always includes `reasoning`; table mode omits it unless
   `--show-reasoning` is passed.
5. `reasoningTokens` (from `usage.completion_tokens_details.reasoning_tokens`)
   is surfaced separately so callers can attribute cost.

## Example

```bash
node plugins/ruflo-deepseek-harness/scripts/reason.mjs \
  --prompt "Prove that sqrt(2) is irrational." \
  --format table --show-reasoning
```

Table output shows the reasoning block, then the answer. JSON mode returns:

```json
{
  "status": "ok",
  "model": "deepseek-reasoner",
  "content": "sqrt(2) is irrational because …",
  "reasoning": "Assume for contradiction that sqrt(2) = p/q in lowest terms …",
  "finishReason": "stop",
  "usage": {
    "promptTokens": 14,
    "completionTokens": 812,
    "reasoningTokens": 640,
    "totalTokens": 826
  }
}
```

