Skip to main content
ZICQ

Skills ZICQ category:Agent Workflows coding-principles

Coding Principles

Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.

73 installs

Official URL:skills.sh

What this skill does

Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.

What it does

Language-agnostic coding principles for maintainability, readability, and quality

When to use it

implementing features, refactoring code, or reviewing code quality

How agents load it

Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Language-Agnostic Coding Principles; Core Philosophy; Code Quality; Continuous Improvement; Readability; Function Design.

File analysis

File analysis: besides SKILL.md, the body references references/security-checks.md. Those resources load on demand.

Language-Agnostic Coding PrinciplesCore PhilosophyCode QualityContinuous ImprovementReadabilityFunction DesignParameter ManagementSingle ResponsibilityFunction OrganizationError HandlingError Management PrinciplesError Propagation

Source category:skills.sh agent-skill

SKILL.md & Agent activation

Official spec ↗
name
coding-principles
description
Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.
  1. DiscoverThe client exposes names and descriptions to the agent.
  2. ActivateYour request or the task context selects the skill and loads its instructions.
  3. Load resourcesReferenced scripts, documentation and assets are used when needed.
Files referenced by the instructions · 1
  • references/security-checks.md

These paths are extracted from the text. Check the upstream package to verify the files exist.

Invocation syntax and available tools depend on your Agent client. Client integration guide ↗

Install this skill

Skills CLI ↗

Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.

This skill references supporting files. Retrieve the complete directory from the source; copying SKILL.md alone may leave missing dependencies.

Ask your Agent to install

Copy these instructions to a compatible agent and confirm the target directory matches your client.

Install the agent skill "coding-principles" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-cc4756a6907bbe41-Coding-Principles.html
Save it as .cursor/skills/coding-principles/SKILL.md or .claude/skills/coding-principles/SKILL.md and keep the frontmatter name and description exactly as-is.
This skill also ships scripts/, references/, or assets/ — fetch the whole folder from https://github.com/shinpr/claude-code-workflows instead of creating only a SKILL.md.

Full package on GitHub ↗

Install from the terminal · Skills CLI

Requires Node.js and npx. First inspect the repository's skill list to confirm the name.

npx skills add 'https://github.com/shinpr/claude-code-workflows' --list

npx skills add 'https://github.com/shinpr/claude-code-workflows' --skill 'coding-principles'

The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.

Readable layout

name: coding-principles description: Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.

Language-Agnostic Coding Principles

Core Philosophy

  1. Maintainability over Speed: Prioritize long-term code health over initial development velocity
  2. Simplicity First: Choose the simplest solution that meets requirements (YAGNI principle)
  3. Design Convergence: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first.
  4. Explicit over Implicit: Make intentions clear through code structure and naming
  5. Delete over Comment: Remove unused code instead of commenting it out

Code Quality

Continuous Improvement

  • Refactor related code inside the accepted outcome and governing boundaries when it reduces the change's risk or maintenance cost
  • Improve code structure incrementally
  • Keep the codebase lean and focused
  • Delete code proven obsolete by the requested change after checking its callers; report uncertain or out-of-scope cleanup separately

Readability

  • Use meaningful, descriptive names drawn from the problem domain
  • Use full words in names; abbreviations are acceptable only when widely recognized in the domain
  • Use descriptive names; single-letter names are acceptable only for loop counters or well-known conventions (i, j, x, y)
  • Extract magic numbers and strings into named constants
  • Keep code self-documenting where possible

Function Design

Parameter Management

  • Group related positional parameters into an object, struct, or dictionary when call-site clarity or coordinated evolution requires it. Retain positional parameters when their order is conventional and the call remains clear, or an external/public signature requires them
  • Preserve external/public signatures unless their migration is part of the accepted outcome or governing artifact

Single Responsibility

  • Each function should do one thing well
  • Extract a function when independently changing responsibilities or obscured control flow make the current unit harder to understand, verify, or reuse; retain a cohesive domain flow when extraction would create artificial coupling
  • Extract complex logic into separate, well-named functions
  • Functions should have a single level of abstraction

Function Organization

  • Pure functions when possible (no side effects)
  • Separate data transformation from side effects
  • Use early returns to reduce nesting
  • Use early returns or extraction when nesting obscures state transitions or decision ownership; retain nested structure when it maps the domain decision more clearly

Error Handling

Error Management Principles

  • Always handle errors: Log with context or propagate explicitly
  • Log appropriately: Include context for debugging
  • Protect sensitive data: Mask or exclude passwords, tokens, PII from logs
  • Fail fast: Detect and report errors as early as possible

Error Propagation

  • Use language-appropriate error handling mechanisms
  • Propagate errors to appropriate handling levels
  • Provide meaningful error messages
  • Include error context when re-throwing

Dependency Management

Loose Coupling via Parameterized Dependencies

  • Inject external dependencies as parameters (constructor injection for classes, function parameters for procedural/functional code)
  • Depend on abstractions, not concrete implementations
  • Minimize inter-module dependencies
  • Facilitate testing through mockable dependencies

Reference Representativeness

Verifying References Before Adoption

When adopting patterns, APIs, or dependencies from existing code:

  • IF a reference sample covers only nearby files → THEN confirm the pattern is representative by checking relevant repository usage before adopting
  • IF multiple approaches coexist in the repository → THEN identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient
  • IF adopting an external dependency (library, plugin, SDK) → THEN verify repository-wide usage and compatibility evidence; when that evidence cannot determine the required version, record the unresolved version decision and the evidence needed to settle it
  • IF following an existing pattern → THEN state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update)

Principle

Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model.

Performance Considerations

Optimization Approach

  • Measure first: Profile before optimizing
  • Focus on algorithms: Algorithmic complexity > micro-optimizations
  • Use appropriate data structures: Choose based on access patterns
  • Resource management: Handle memory, connections, and files properly

When to Optimize

  • After identifying actual bottlenecks through profiling
  • When performance issues are measurable
  • Optimize only after measurable bottlenecks are identified, not during initial development

Code Organization

Structural Principles

  • Group related functionality: Keep related code together
  • Separate concerns: Domain logic, data access, presentation
  • Consistent naming: Follow project conventions
  • Module cohesion: High cohesion within modules, low coupling between

File Organization

  • One primary responsibility per file
  • Logical grouping of related functions/classes
  • Clear folder structure reflecting architecture
  • Split a file when it contains independently changing responsibilities or creates material navigation, coupling, or verification cost; retain a cohesive file when splitting would add avoidable coupling or navigation cost

Commenting Principles

Default: code first

Names, types, and structure are the primary medium. A comment earns its place only by carrying information the code itself cannot express. When in doubt, improve the name instead of adding a comment.

The test for every comment

A comment is justified only if it answers one of these:

  • Why: reasoning, trade-off, or constraint behind a non-obvious decision
  • Limitation / edge case: a boundary a reader cannot infer from the code
  • Public API contract: behavior, inputs, outputs of an exported interface

One comment per decision. If a comment restates what the names and control flow already show, delete it and rename instead.

Comment Scope

  • Comment the why, limits, and public contracts (per the test above); let names and structure carry everything else, including the "how"
  • Record historical context in version control commit messages, not in comments
  • Delete commented-out code (retrieve from git history when needed)

Comment Quality

  • Base comments on stable rationale, limits, and contracts rather than dates, versions, or temporary state
  • Update comments when changing code
  • Use proper grammar and formatting
  • Write for future maintainers

Refactoring Approach

Safe Refactoring

  • Small steps: Make one change at a time
  • Maintain working state: Keep tests passing
  • Verify behavior: Run tests after each change
  • Incremental improvement: Make the smallest sufficient improvement in each increment

Refactoring Triggers

  • Code duplication (DRY principle)
  • Functions that contain independently changing responsibilities or obscured control flow
  • Complex conditional logic
  • Unclear naming or structure

Security Principles

Secure Defaults

  • Store credentials and secrets through environment variables or dedicated secret managers
  • Use parameterized queries (prepared statements) for all database access
  • Use established cryptographic libraries provided by the language or framework
  • Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators
  • Encrypt sensitive data at rest and in transit using standard protocols

Input and Output Boundaries

  • Validate all external input at system entry points for expected format, type, and length
  • Encode output appropriately for its rendering context (HTML, SQL, shell, URL)
  • Return only information necessary for the caller in error responses; log detailed diagnostics server-side

Access Control

  • Apply authentication to all entry points that handle user data or trigger state changes
  • Verify authorization for each resource access, not only at the entry point
  • Grant only the permissions required for the operation (files, database connections, API scopes)
  • For changes involving identity or protected resources, prioritize authentication and per-resource authorization review

For concrete detection patterns used by security review, see references/security-checks.md.

Related skills

Agent Workflows

Skill Creator

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that exte…

Agent Workflows

Clawdhub

Use the ClawdHub CLI to search, install, update, and publish agent skills from clawdhub.com. Use when you need to fetch new skills on the fl…

Agent Workflows

Agent Team Orchestration

Orchestrate multi-agent teams with defined roles, task lifecycles, handoff protocols, and review workflows. Use when: (1) Setting up a team …

Agent Workflows

Superpowers

Spec-first, TDD, subagent-driven software development workflow. Use when: (1) building any new feature or app — triggers brainstorm → plan →…