software-craft_skill

Overview

This skill guides engineering judgment for design decisions, trade-offs, code quality, and project-level priorities. It codifies principles for simplicity, safety, type-safety, testing, refactoring, performance, and communication so you make consistent, pragmatic choices. Use it to decide when to act independently, when to ask, and when to escalate.

How this skill works

The skill inspects the problem context, existing codebase patterns, and stated requirements to recommend an approach that balances speed, maintainability, and safety. It evaluates trade-offs (simplicity vs flexibility, speed vs robustness), suggests concrete constraints for changes (size, tests, documentation), and flags high-risk areas that require questions or escalation. It also enforces non-negotiables like input validation, explicit error handling, and no secrets in code.

When to use it

• Making architectural or design decisions
• Evaluating trade-offs between alternative approaches
• Deciding if code needs refactoring or tests
• Determining appropriate level of thoroughness for a change
• Assessing whether to proceed independently or ask for input
• Balancing delivery speed with long-term maintainability

Best practices

• Read existing patterns and project rules before changing code
• Prefer the simplest solution that satisfies requirements; add complexity only when necessary
• Make small, focused commits (single idea, ~20–100 LOC, 1–5 files) with tests
• Make illegal states unrepresentable; prefer discriminated unions and explicit result types
• Validate external input and handle every error path explicitly
• Document non-obvious decisions and trade-offs in PR description or comments

Example use cases

• Choose between integrating a proven library or writing a small custom utility
• Decide whether to refactor duplicated logic when adding a related feature
• Set testing scope for a public interface and critical error paths
• Assess if a performance issue needs profiling and targeted optimization
• Determine whether a proposed change requires team discussion or can be shipped autonomously