Skip to main content
software-craft This skill should be used when making design decisions, evaluating trade-offs, assessing code quality, or when engineering judgment or code quality are mentioned.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/outfitter-dev/outfitter --skill software-craftThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... Related occupations SOC
Based on SOC occupation classification
More from this repository Patterns for @outfitter/daemon including lifecycle management, IPC communication, health checks, and PID files. Use when building background services, daemons, or when "daemon", "IPC", "health check", "background service", or "@outfitter/daemon" are mentioned.
Creates handlers, CLI commands, MCP tools, and daemon services following Outfitter Dev Kit conventions. Use when adding new components to a project, scaffolding code, or when "create handler", "new command", "add tool", or "daemon service" are mentioned.
Deep patterns for @outfitter/mcp including tool registration, Zod schemas, resources, and server configuration. Use when building MCP servers, registering tools, defining resources, or when "MCP server", "MCP tool", "registerTool", or "@outfitter/mcp" are mentioned.
name software-craft description This skill should be used when making design decisions, evaluating trade-offs, assessing code quality, or when engineering judgment or code quality are mentioned. metadata {"version":"1.0.1"}
Software Engineering
Engineering judgment - thoughtful decisions - quality code.
<when_to_use>
Making architectural or design decisions
Evaluating trade-offs between approaches
Determining appropriate level of thoroughness
Assessing when code needs refactoring
Deciding when to ask vs proceed independently
Balancing speed, quality, maintainability
NOT for: mechanical tasks, clear-cut decisions, following explicit instructions
</when_to_use>
Core engineering judgment framework.
User preferences trump defaults
CLAUDE.md, project rules, existing patterns always override skill suggestions.
Simplest thing that works
Start simple. Add complexity only when requirements demand.
Boring solutions for boring problems
Proven libraries over custom implementations
Progressive enhancement over rewrites
Read before write
Understand existing patterns before modifying.
Check how similar features implemented
Follow established conventions
Maintain consistency
Small, focused changes
One idea per commit, 20-100 LOC, 1-5 files.
Easy to review/understand
Lower bug risk
Simpler to revert
Faster feedback Security awareness
Don't introduce vulnerabilities.
Validate external input
Parameterized queries
Handle auth properly
No secrets in code/logs
Know when to stop
Ship working code, don't gold-plate.
Implement requirements, not assumptions
No unrequested features
No speculative abstraction
Type safety across languages.
Core principle : Make illegal states unrepresentable. Type system should prevent invalid data at compile time, not runtime.
Hierarchy : Correct (type-safe) - Clear (self-documenting) - Precise (not overly broad)
Result types - Errors explicit in signatures, not hidden in exceptionsDiscriminated unions - Mutually exclusive states with discriminator fieldBranded types - Distinct types for domain concepts (user ID vs product ID)Parse, don't validate - Transform untyped to typed at boundaries, trust types internally See type-patterns.md for detailed concepts.
Load typescript-fieldguide/SKILL.md for TypeScript implementations.
Systematic approach to engineering choices.
Understand before deciding
What problem being solved?
What constraints exist?
What's already in codebase?
What patterns does project use?
Consider trade-offs
No perfect solutions:
Speed vs robustness
Simplicity vs flexibility
Consistency vs optimization
Implement time vs maintain time
Recognize good-enough
Perfect is enemy of shipped:
Meets requirements?
Maintainable by team?
Tested adequately?
Can improve incrementally?
Document significant choices
Non-obvious decisions: comment why, note trade-offs, link discussions, flag assumptions.
Balance autonomy with collaboration.
Task clear and well-defined
Approach follows existing patterns
Changes small and localized
Requirements fully understood
No security/data integrity risks
Requirements ambiguous
Multiple approaches, unclear trade-offs
Changes affect architecture
Security/compliance implications
Unfamiliar domain/technology
Security vulnerabilities discovered
Data corruption/loss risk
Breaking changes to public APIs
Performance degradation detected
Don't guess on high-stakes decisions.
Standards separating good from professional code.
Type safety : Make illegal states unrepresentable via discriminated unions, branded types.
Error handling : Every error path needs explicit handling. No silent failures.
Naming : Functions=verbs (calculateTotal), variables=nouns (userId), booleans=questions (isValid).
Function design : One thing well. 10-30 lines typical, max 50. 3 params ideal, max 5. Pure when possible.
Comments : Explain why, not what.
When and how to improve existing code.
Adding feature reveals poor structure
Code duplicated 3+ times
Function exceeds 50 lines
Naming unclear/misleading
Tests difficult to write
Code works and won't be touched
Time-critical delivery in progress
No test coverage to verify
Scope creep from main task
Just preference, no clear benefit
Have tests first (or write them)
One refactoring at a time
Keep tests passing throughout
Commit refactors separately from features
Don't change behavior
Public interfaces, not implementation
Edge cases and error paths
Critical business logic
Integration points
Security boundaries
No tests for trivial getters/setters
Don't test framework behavior
Avoid brittle implementation-coupled tests
Critical paths: 90%+
Business logic: 80%+
Utility functions: 80%+
Overall: 70%+
Low coverage acceptable for: config, type definitions, framework boilerplate.
Balance optimization with delivery.
Premature optimization is root of evil
Make it work first
Make it right second
Make it fast only if needed
Measured performance issue exists
User experience degraded
Resource costs excessive
Profiler shows clear bottleneck
Measure current performance
Set target metrics
Profile to find bottleneck
Optimize specific bottleneck
Measure improvement
Document trade-offs
Don't optimize based on gut feeling or without measurement.
Security mindset for all code.
Input validation : Validate all external input, sanitize before processing, allowlists over blocklists.
Auth : Never trust client-side checks, verify on server, use proven libraries, don't roll your own crypto.
Data handling : Never log sensitive data, hash passwords (bcrypt/argon2), parameterized queries, strict file upload validation.
Dependencies : Keep updated, review advisories, minimize count, audit before adding.
Red flags to escalate : Payment info, user credentials, health/financial data, encryption implementation, session management.
Common mistakes to avoid.
Over-engineering : Building "might need" features, premature abstraction, excessive config, enterprise patterns for simple problems.
Fix: YAGNI. Build for today.
Under-engineering : No error handling, no input validation, ignoring edge cases, copy-paste over functions.
Fix: Basic quality isn't optional.
Scope creep : "While I'm here...", refactoring unrelated code, adding unrequested features.
Fix: Stay focused. File issues for unrelated work.
Guess-and-check : Random solutions, copying without understanding, no root cause investigation.
Fix: Systematic debugging. Understand before changing.
Analysis paralysis : Endless design discussions, researching every option, waiting for perfect.
Fix: Good enough + shipping > perfect + delayed.
Senior engineer collaboration.
Clear issues/PRs : Context (problem), approach (solution), trade-offs (alternatives), testing (verification), impact (risks).
Code review : Focus on correctness/clarity/security. Suggest, don't demand perfection. Approve when good enough.
When blocked : Try 30 min self-unblock, gather context, ask specific question with context, propose solutions.
Saying no : "That would work, but have you considered X?" / "This introduces Y risk. Can we mitigate with Z?"
Back opinions with reasoning. Stay open to being wrong.
Connect with other outfitter skills.
With TDD : Senior judgment decides what's worth testing. TDD skill provides how.
With debugging : Senior judgment decides if worth fixing now. Debugging skill provides systematic investigation.
With dev-* skills : Software engineering provides the "why" and "when". dev-* skills provide the "how" for specific technologies (typescript-fieldguide, react-fieldguide, hono-fieldguide, bun-fieldguide).
Read CLAUDE.md and project rules first
Follow existing codebase patterns
Make small, focused changes
Validate external input
Handle errors explicitly
Test critical paths
Document non-obvious decisions
Ask when uncertain on high-stakes
Add features not in requirements
Ignore error handling
Skip input validation
Commit secrets or credentials
Guess on security decisions
Refactor without tests
Optimize without measuring
Over-engineer simple solutions
Complements other outfitter skills:
Development Skills (load for implementation patterns):
