Skip to main content
skill CX Codex

ds-principles — Claude Code skill: what it does, how to install

A skill for Claude Code and Cursor that provides engineering principles for design, debugging, and verification. The agent applies them during code structure choices, diff sizing, or when typing /ds-principles.

MIT 557 installs ★ 320 updated 2026-10-28

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add aicodeking/deepseek-stack --skill ds-principles -a claude-code
Open on GitHub

What ds-principles does

The skill structures agent behavior through precise rules covering data shape, state isolation, and root-cause debugging. It mandates removing dead code first, validating inputs at system boundaries, and asserting observable behavior in tests.

Triggers fire automatically during refactoring or test writing, prohibiting types like any and unvalidated casts.

The /ds-principles command invokes the entire checklist directly inside the active coding session.

What it helps with

  • design data structures before core logic
  • isolate root causes during debugging
  • assert observable behavior in tests
  • split a large migration into verifiable steps

Example prompts for the agent

  • Apply ds-principles to this data model
  • Check this diff against ds-principles rules
  • Run /ds-principles before debugging this module

How to install ds-principles

1Skills CLI (Vercel)

npx skills add aicodeking/deepseek-stack --skill ds-principles -a claude-code

2Manually: put the files in place

~/.claude/skills/ds-principles/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ds-principles/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ds-principles

How to install ds-principles in Claude Code?

Run npx skills add aicodeking/deepseek-stack --skill ds-principles -a claude-code and verify ~/.claude/skills/ds-principles/SKILL.md.

What does ds-principles do?

Supplies compact engineering principles for software design, debugging, and testing that the agent follows via triggers or commands.

What is required to run ds-principles?

No external API keys or background services are needed; the skill runs natively inside supported AI coding environments.

Source text

SKILL.md · MIT
---
name: ds-principles
description: "Compact engineering principles for design, debugging, verification, and delegation, each with a trigger. Use when choosing structure or types, sizing a diff, debugging, writing tests, or when the user types /ds-principles."
---

# Engineering principles

If a trigger matches, apply the rule. Name principles that changed a decision.

## Design

1. **Subtract, then add little.** Remove dead code and stale checks first, then make the shortest diff that works. No abstraction with one user. Apply when sizing a diff or tempted to add a layer.
2. **Data shape first.** Choose the core types and structures before logic. Apply before writing new logic.
3. **Model the domain.** Put states in one structure, such as a typed union, state machine, or lookup table, not scattered conditionals. Apply when code branches a lot or repeats a shape across files.
4. **Redesign for the new need.** Fit a new requirement as if it existed from day one. Apply when an addition strains the design.
5. **Low reader load.** Inline one-caller wrappers and shrink mutable scope. Apply when code is hard to trace.
6. **Guards at boundaries.** Validate where input enters: CLI, config, network, files, external APIs. Trust types inside and keep core logic pure. Apply when adding validation or error handling.
7. **Idempotent steps.** Rerunning a step, even after a crash, reaches the same state. Apply to commands, setup, and retries.
8. **No shared writers.** Give each concurrent actor its own file, branch, or key before using locks. Apply when parallel work touches shared state.
9. **Migrate, then delete.** Move every caller and delete the old API in one change. No shims. Apply when replacing an API or rewriting in phases.
10. **Compare options.** For an unprecedented design, sketch two or three. Prefer fewer, polished features. Apply to novel architecture, UX, or scope choices.

## Debugging and verification

11. **Fix root causes.** Fix where state first went wrong. A guard fixes only legitimate states. Apply when debugging.
12. **Attack the premise.** After two failed fixes that share an assumption, write it down and test it directly. Apply before a third attempt.
13. **Prove it works.** Run the real thing and read the actual output, not a proxy. Apply before claiming done.
14. **Verifiable units.** Split work into steps that each end in a passing check. Apply to sweeps, migrations, and stacked commits.
15. **Test behavior.** Assert what callers can observe, so tests survive refactors. Apply when writing or keeping a test.
16. **Explain the number.** Find what limits a measurement and confirm it measured the right work. Apply to benchmarks and eval scores.
17. **Build the tool.** Script bulk or repeated work so it can be rerun. Apply to large edit sets or checks.

## Process

18. **Guard the context.** Keep summaries, not dumps. Send bulk reading to subagents. Apply when outputs or files are large.
19. **Do not block on the human.** On reversible work, proceed and show the result. Apply when tempted to ask "should I?".
20. **Encode repeated lessons.** A correction given twice becomes a lint, test, or script. Apply when a mistake recurs.
21. **Comments explain why.** Keep a comment only for a reason the code cannot show, such as an external constraint or a public API contract. Delete narration and dead code. Fix code whose surprise needs a comment. Apply when writing or reviewing code.

## Types

- Make illegal states unrepresentable. Use discriminated unions, not optional-field bags.
- Parse external data once at the boundary into a named type. Trust it inside.
- Use `unknown` for untrusted input. Never `any`. No `as` casts before validation.
- Derive types from a schema, not hand-written guards.
- Add a `never` check in default branches so new variants fail the build.
- Brand primitives that must not mix, such as user IDs and order IDs.

© aicodeking · MIT · aicodeking/deepseek-stack

Similar skills

All skills for Agent setup: memory, context, orchestration →
solid-principles TheBushidoCollective solid-principles is a Claude Code skill for applying SOLID while designing modules, functions, and components. It activates during implementation work on code architecture. CX Codex +1 611installs principle-redesign-from-first-principles backnotprop principle-redesign-from-first-principles — a skill that makes the agent rebuild an existing design as if the new requirement had been there from day one. Use it when a change ripples through types, docs, and examples. CX Codex +1 10,200installs clean-code-principles AsyrafHussin clean-code-principles — a skill for architecture review and code quality: SOLID, DRY, KISS, design patterns. Useful when refactoring or weighing design decisions. CX Codex +1 1,900installs software-design-principles databricks-solutions software-design-principles — a Markdown engineering guide for code review, module planning, and refactoring. It enforces clean boundaries, non-functional requirements, and layered design across pull requests. CX Codex +1 ★ 38repo stars thinking-first-principles tjboudreaux thinking-first-principles — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that separates real constraints from inherited convention and rebuilds from primitives. CX Codex +1 844installs dotnet-solid-principles wshaddix dotnet-solid-principles — a skill for Claude Code that applies SOLID, DRY, and SRP principles in .NET projects. Detects C# anti-patterns and suggests specific refactoring steps. CX Codex +1 112installs

From the same set29

The whole set →
ds-plan-loop The ds-plan-loop Claude Code skill builds a plan with a check for each step, reviews it, then carries out the task one step at a time. It activates for multi-file work, unclear scope, or tasks that previously missed steps. CX Codex +1 569installs ds-mode This Claude Code skill sets a coding workflow around reading first, making small edits, and checking results. It activates at the start of a coding task, on /ds-mode, or when work starts to drift. CX Codex +1 567installs ds-unstick ds-unstick — a Claude Code skill breaks repeating failure loops by testing core assumptions. It runs when the same error returns after two failed fix attempts. CX Codex +1 566installs ds-context-reset ds-context-reset is a Claude Code skill that manages context resets for long tasks using a PROGRESS.md tracking file. CX Codex +1 562installs ds-blast-radius The ds-blast-radius Claude Code skill checks what a change might break beyond its diff, then tests a key safety claim by running code. Use it to inspect risky or untrusted changes before shipping. CX Codex +1 550installs ds-help ds-help — a Claude Code skill that picks the right deepseek-stack tool for a task and explains how the pack fits together. CX Codex +1 549installs ds-design-audit ds-design-audit audits an interface using evidence from screenshots and code, fixes the highest-impact issues, and verifies the outcome. Runs before shipping UI work or when a screen looks cluttered. CX Codex +1 548installs ds-design ds-design — a Claude Code skill for setting a distinct visual direction for frontend work. It runs when creating a page, app screen, or component, and when restyling an existing interface. CX Codex +1 548installs

Project sponsors

Companies that keep this analytics open