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
npx skills add aicodeking/deepseek-stack --skill ds-principles -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/ds-principles/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ds-principles/
1Skills CLI (Vercel)
npx skills add aicodeking/deepseek-stack --skill ds-principles -a codex2Manually: put the files in place
.agents/skills/ds-principles/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add aicodeking/deepseek-stack --skill ds-principles -a cursor2Manually: put the files in place
.cursor/skills/ds-principles/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install aicodeking/deepseek-stack skills/ds-principles2Manually: put the files in place
.github/skills/ds-principles/SKILL.md1Skills CLI (Vercel)
npx skills add aicodeking/deepseek-stack --skill ds-principles -a gemini-cli2Platform CLI
gemini skills install https://github.com/aicodeking/deepseek-stack --path skills/ds-principlesManually: put the files in place
.devin/skills/ds-principles/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add aicodeking/deepseek-stack --skill ds-principles -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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