Skill: programming-practices-core
Activation Contract
Use this skill when asked to review, explain, or improve general programming practices across languages: readability, maintainability, duplication, cohesion, coupling, naming, simplicity, and safe evolution.
Do not use this skill when the request is only formatting, framework setup, performance tuning, security auditing, testing, or language-specific API usage with no broader design-quality question.
Responsibility
This skill teaches a bounded code-quality review workflow. It does not choose tools, call other skills, rewrite whole systems, or replace domain requirements supplied by the user.
Required Context
- Target language and code snippet/files, if available.
- Intended behavior and current pain point.
- Constraints: legacy-code safety, public API compatibility, deadline, or team conventions.
- Whether the user wants diagnosis only or an improvement plan.
Context Budget
- Keep this
SKILL.md focused on the executable contract.
- Use
references/principles.md only when the request needs deeper tradeoff language.
Hard Rules
- Prefer clarity over cleverness.
- Treat DRY as “avoid duplicating knowledge,” not “remove every repeated line.”
- Do not recommend abstractions before identifying a stable concept or repeated reason to change.
- Preserve observable behavior unless the user explicitly asks for behavior change.
- Name tradeoffs: simplicity, coupling, cohesion, testability, discoverability, and change cost.
- Ask one clarifying question only when missing context could change the recommendation materially.
Decision Gates
| Condition |
Action |
| Code is hard to read but behavior is clear |
Recommend naming, extraction, structure, and intent-revealing changes. |
| Duplication exists |
Classify it as duplicated knowledge, coincidental repetition, or premature abstraction risk. |
| User asks for “best practices” with no code |
Give a principle map and ask for code/context before prescribing changes. |
| Proposed improvement adds indirection |
Justify the indirection with a real change scenario or reject it. |
Execution Steps
- Identify the code’s purpose and current change pressure.
- Separate readability issues from design issues.
- Classify duplication and abstraction opportunities.
- Recommend the smallest behavior-preserving improvement first.
- Explain the tradeoff and what not to change yet.
- Return a prioritized plan or focused review.
Output Contract
Return:
- Summary verdict:
healthy, needs_cleanup, or design_risk.
- Top issues, ordered by impact.
- Recommended changes with reasoning.
- Tradeoffs and risks.
- One next step.
References
references/principles.md — Core principles and tradeoff language.
Assets
1---2name: programming-practices-core3description: Trigger: programming best practices, clean code, DRY, KISS, YAGNI, readability, maintainability. Evaluate general code quality without depending on language-specific skills.4license: MIT5---67# Skill: programming-practices-core89## Activation Contract1011Use this skill when asked to review, explain, or improve general programming practices across languages: readability, maintainability, duplication, cohesion, coupling, naming, simplicity, and safe evolution.1213Do **not** use this skill when the request is only formatting, framework setup, performance tuning, security auditing, testing, or language-specific API usage with no broader design-quality question.1415## Responsibility1617This skill teaches a bounded code-quality review workflow. It does not choose tools, call other skills, rewrite whole systems, or replace domain requirements supplied by the user.1819## Required Context2021- Target language and code snippet/files, if available.22- Intended behavior and current pain point.23- Constraints: legacy-code safety, public API compatibility, deadline, or team conventions.24- Whether the user wants diagnosis only or an improvement plan.2526## Context Budget2728- Keep this `SKILL.md` focused on the executable contract.29- Use `references/principles.md` only when the request needs deeper tradeoff language.3031## Hard Rules3233- Prefer clarity over cleverness.34- Treat DRY as “avoid duplicating knowledge,” not “remove every repeated line.”35- Do not recommend abstractions before identifying a stable concept or repeated reason to change.36- Preserve observable behavior unless the user explicitly asks for behavior change.37- Name tradeoffs: simplicity, coupling, cohesion, testability, discoverability, and change cost.38- Ask one clarifying question only when missing context could change the recommendation materially.3940## Decision Gates4142| Condition | Action |43|---|---|44| Code is hard to read but behavior is clear | Recommend naming, extraction, structure, and intent-revealing changes. |45| Duplication exists | Classify it as duplicated knowledge, coincidental repetition, or premature abstraction risk. |46| User asks for “best practices” with no code | Give a principle map and ask for code/context before prescribing changes. |47| Proposed improvement adds indirection | Justify the indirection with a real change scenario or reject it. |4849## Execution Steps50511. Identify the code’s purpose and current change pressure.522. Separate readability issues from design issues.533. Classify duplication and abstraction opportunities.544. Recommend the smallest behavior-preserving improvement first.555. Explain the tradeoff and what not to change yet.566. Return a prioritized plan or focused review.5758## Output Contract5960Return:6162- Summary verdict: `healthy`, `needs_cleanup`, or `design_risk`.63- Top issues, ordered by impact.64- Recommended changes with reasoning.65- Tradeoffs and risks.66- One next step.6768## References6970- `references/principles.md` — Core principles and tradeoff language.7172## Assets7374- None.
andresnator