Foundational coding principles as AI agent skills. KISS, DRY, SOLID, YAGNI, Separation of Concerns, Law of Demeter, Boy Scout Rule, Convention over Configuration — plus a stack detection skill that makes them all language-aware. Works with Claude Code, OpenAI Codex, Cursor, Windsurf, and any agent that supports the Agent Skills spec.
Built by Jordan Coin Jackson. Contributions welcome — open a PR or file an issue.
Skills are markdown files that give AI agents specialized knowledge for specific tasks. These skills teach agents how to think about code quality — not syntax, not framework APIs, but the principles that separate code that ships reliably from code that breaks in production.
Each skill includes:
- Rules — concrete, actionable guidelines (not platitudes)
- Anti-patterns — what violations actually look like in real code
- Examples — before/after showing the principle applied
- Boundaries — when NOT to apply the principle (every principle has limits)
- Code review checklist — for agents reviewing PRs or auditing codebases
Every skill reads .agents/stack-context.md first (generated by detect-stack) to understand the project's language, framework, and conventions. Then it applies the principle idiomatically — Rust patterns for Rust, Python patterns for Python, etc.
┌──────────────────────────────────────┐
│ detect-stack │
│ (generates stack-context.md) │
└──────────────────┬───────────────────┘
│
│ read by all skills
│
┌────────┬──────────┬───────────────┼────────────┬──────────┬──────────────┐
│ │ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼ ▼
┌──────┐ ┌──────┐ ┌────────┐ ┌──────────────┐ ┌────────┐ ┌────────┐ ┌────────────┐
│ KISS │ │ DRY │ │ SOLID │ │ Separation │ │ Law │ │ Boy │ │ Convention │
│ │ │ │ │ │ │ of Concerns │ │ of │ │ Scout │ │ over │
│ │ │ │ │ │ │ │ │Demeter │ │ Rule │ │ Config │
└──┬───┘ └──┬───┘ └───┬────┘ └──────┬───────┘ └───┬────┘ └───┬────┘ └─────┬──────┘
│ │ │ │ │ │ │
└────────┴────┬────┴─────────────┴─────────────┴──────────┴─────────────┘
│
Skills cross-reference each other:
kiss ↔ yagni ↔ solid
separation-of-concerns ↔ solid ↔ law-of-demeter
boy-scout-rule ↔ convention-over-configuration ↔ kiss
See each skill's Related Skills section for the full dependency map.
| Skill | Description |
|---|---|
| kiss | Reduce complexity and improve readability. Use when code is "too complex," "hard to read," or "can't follow this." |
| dry | Eliminate duplicated knowledge and business logic. Use when "this is duplicated" or "we have this in two places." |
| yagni | Prevent over-engineering and speculative features. Use when code is "over-engineered" or builds for "just in case." |
| solid | Design module boundaries and interfaces for maintainable architecture. SRP, OCP, LSP, ISP, DIP. |
| separation-of-concerns | Structure code into layers with clear boundaries. Use when "this function does too much" or "fat controller." |
| law-of-demeter | Reduce coupling and deep object chains. Use when code has "train wrecks" or "mocking is painful." |
| boy-scout-rule | Leave code better than you found it — incrementally. Use when touching existing code and spotting small improvements. |
| convention-over-configuration | Establish patterns and reduce configuration overhead. Use when "too much config" or "inconsistent structure." |
| detect-stack | Analyze a codebase to detect language, framework, conventions, and CI gates. Generates .agents/stack-context.md. |
# Install all skills
npx skills add JordanCoin/codingskills
# Install specific skills
npx skills add JordanCoin/codingskills --skill kiss dry solid
# List available skills
npx skills add JordanCoin/codingskills --list/plugin marketplace add JordanCoin/codingskills
/plugin install coding-skillsgit clone https://github.com/JordanCoin/codingskills.git
cd your-project && /path/to/codingskills/install.shThis copies skills to .agents/skills/ and symlinks .claude/skills/ for Claude Code compatibility.
git submodule add https://github.com/JordanCoin/codingskills.git .agents/codingskillsFork, tweak the principles for your team's conventions, clone into your projects.
npx skillkit install JordanCoin/codingskillsOnce installed, just ask your agent to help with code quality:
"Simplify this function"
→ Uses kiss skill
"Is this over-engineered?"
→ Uses yagni skill
"Review this PR for code quality"
→ Uses kiss, dry, law-of-demeter skills
"Audit this codebase for tech debt"
→ Uses all skills sequentially
Invoke skills directly:
/kiss
/dry
/solid
/yagni
/separation-of-concerns
/law-of-demeter
/boy-scout-rule
/convention-over-configuration
/detect-stack
| Situation | Primary | Supporting |
|---|---|---|
| Adding a new feature | yagni | kiss, separation-of-concerns |
| Refactoring | separation-of-concerns, solid | dry, boy-scout-rule |
| Reviewing a PR | kiss, dry | law-of-demeter, convention-over-configuration |
| Fixing a bug | boy-scout-rule, kiss | separation-of-concerns |
| Designing module boundaries | separation-of-concerns, solid | law-of-demeter |
| Choosing between approaches | kiss, yagni | convention-over-configuration |
| Organizing project structure | convention-over-configuration | separation-of-concerns, solid |
| Reducing coupling | law-of-demeter, solid | separation-of-concerns |
| Auditing for tech debt | all | run detect-stack first, then each principle |
The detect-stack skill scans your project and generates .agents/stack-context.md with:
- Language and version
- Framework and database layer
- Build, test, lint, and format tools
- CI gate configuration
- Project conventions and naming patterns
Every other skill reads this file first and applies principles idiomatically for your stack. No static reference files per language — agents use their built-in knowledge plus context7 MCP for framework-specific details on demand.
Found a way to improve a skill? Have a new principle to add? PRs and issues welcome.
See CONTRIBUTING.md for guidelines.
MIT — use these however you want.