smith-style

tianjianjiang's avatarfrom tianjianjiang

File naming, path standards, and conventional commits. Use when naming files, creating branches, writing commit messages, or setting up new projects. Covers underscore vs hyphen conventions, commit format, and branch naming patterns.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026
[Developer Tools]

When & Why to Use This Skill

This Claude skill establishes and enforces rigorous standards for project organization and version control. It provides clear logic for file naming conventions (distinguishing between underscores and hyphens), directory structures, and standardized Git workflows, including Conventional Commits and branch naming patterns to ensure codebase consistency and maintainability.

Use Cases

  • New Project Initialization: Setting up a standardized file and directory structure from the start to prevent technical debt and naming inconsistencies.
  • Git Workflow Standardization: Generating or validating Conventional Commit messages and branch names to facilitate automated changelogs and cleaner repository history.
  • Code Review Automation: Using the skill as a reference point during PRs to ensure all new files and branches adhere to the 'smith-style' naming separators and hierarchical rules.
  • Test Data Organization: Implementing consistent patterns for test files and JSON mock data to improve the discoverability and scalability of test suites.
namesmith-style
descriptionFile naming, path standards, and conventional commits. Use when naming files, creating branches, writing commit messages, or setting up new projects. Covers underscore vs hyphen conventions, commit format, and branch naming patterns.

File Naming & Path Standards

  • Load if: Git operations, PR workflows, new project setup
  • Prerequisites: @smith-principles/SKILL.md

CRITICAL: Naming Separators (Primacy Zone)

Underscore (_): Multi-word phrases as single concept

  • user_authentication, query_processor, semantic_search
  • Think: "What kind of X?" → underscore

Hyphen (-): Hierarchical/parallel relationships

  • auth-login (login is part of auth)
  • api-rest vs api-graphql (variants)
  • Dates: 2025-01-15
  • Tickets: JIRA-1234

File Patterns

Test files: test_[module]_[function]_[type].py JSON test data: [module]_[function]_cases.json Documentation: [topic].md (hyphen for hierarchy, underscore for phrases) Config: .env, pyproject.toml, AGENTS.md

Path References

Use code blocks, not Markdown links:

**Core Principles**: @smith-principles/SKILL.md - Description
**Related Skill**: @skill-name/SKILL.md - Description

Variables: $WORKSPACE_ROOT, $REPO_ROOT, $HOME

Conventional Commits

Format: type: description or type(scope): description

Types: feat, fix, docs, refactor, style, test, chore, perf, build, ci

Length limits (50/72 rule):

  • Subject: 50 chars target, 72 max
  • Body: 72 chars per line
feat(auth): add token refresh
fix: resolve CORS issues
docs: update deployment guide
  • Subject over 72 characters
  • Multiple unrelated changes ("add X and fix Y")
  • Using docs when also changing code

Branch Names

Pattern: type/descriptive_name

Examples:

  • feat/user_authentication (underscore: single concept)
  • feat/auth-login (hyphen: login is part of auth)
  • fix/JIRA-1234-query_processor

Branch type MUST match commit type

  • feat/user-authentication (should be underscore)
  • feat/auth_login (should be hyphen)
  • @smith-git/SKILL.md - Branch and commit workflows
  • @smith-principles/SKILL.md - Core principles (DRY, KISS, YAGNI)

ACTION (Recency Zone)

Before naming:

  1. Is it a single concept? → underscore
  2. Is it a part/variant? → hyphen
  3. Is it a date/ticket? → hyphen

Before committing:

  1. Subject ≤72 chars?
  2. Single atomic change?
  3. Type matches branch?