playbooks

home / skills / tlabs-xyz / tbtc-v2-performance / global-conventions

global-conventions skill

/.claude/skills/global-conventions

This skill enforces global project conventions, guiding structure, docs, config, dependencies, and workflows to improve consistency and collaboration.

npx playbooks add skill tlabs-xyz/tbtc-v2-performance --skill global-conventions

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.0 KB
---
name: Global Conventions
description: Follow project-wide development conventions including consistent project structure, clear documentation, version control best practices, environment configuration, and dependency management. Use this skill when organizing project structure or directories, writing or updating README files, creating documentation, writing commit messages, managing environment variables or configuration files (.env, config files), managing dependencies (package.json, requirements.txt, Cargo.toml, go.mod), implementing feature flags, maintaining changelogs, setting up code review processes, or defining testing requirements. Use across all project organization work regardless of language or framework, including when working with version control, project configuration, or development workflows.
---

## When to use this skill

- When organizing project structure or directory layouts
- When writing or updating README files, documentation, or contribution guidelines
- When writing commit messages or creating pull/merge requests
- When managing environment variables or configuration files (.env, config.yml, settings files)
- When managing project dependencies (package.json, requirements.txt, Cargo.toml, go.mod, Gemfile)
- When implementing feature flags or configuration toggles
- When maintaining changelogs or release notes
- When setting up or following code review processes
- When defining testing requirements or coverage expectations
- When ensuring secrets or API keys are not committed to version control
- When creating or updating architecture documentation
- When establishing project-wide conventions or standards
- When working with version control systems (Git, SVN, Mercurial)

# Global Conventions

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle global conventions.

## Instructions

For details, refer to the information provided in this file:
[global conventions](../../../agent-os/standards/global/conventions.md)

Overview

This skill enforces project-wide development conventions to keep repositories consistent, secure, and easy to navigate. It standardizes project structure, documentation, commit practices, environment configuration, and dependency management across languages and frameworks. Use it to reduce onboarding friction, prevent common mistakes, and simplify reviews and releases.

How this skill works

The skill inspects project layout, README and docs, configuration files (.env, config.yml), dependency manifests (package.json, requirements.txt, Cargo.toml, go.mod), commit messages, changelogs, and feature-flag patterns. It flags missing or inconsistent conventions, recommends fixes (file locations, naming, ignore rules), and suggests secure handling for secrets and environment variables. It also provides templates and examples for README sections, commit message formats, changelog entries, and code review checklists.

When to use it

  • Organizing or reorganizing project directory structure
  • Writing or updating README, contribution guides, or architecture docs
  • Creating commit messages, pull/merge requests, or release notes
  • Managing environment variables, config files, or secret handling
  • Adding or auditing dependencies and dependency files
  • Defining testing, review, or feature-flag conventions

Best practices

  • Keep a single source of truth for configuration and document expected file locations
  • Store secrets outside source control; use .env templates and gitignore entries
  • Use a clear commit message convention (type:scope: short summary) and require changelog entries for releases
  • Pin or lock dependencies where reproducibility matters; document upgrade policy
  • Include concise README sections: purpose, quick start, environment, tests, contribution, license

Example use cases

  • Reformatting a repo to follow a standard src/, tests/, docs/ layout and updating README examples
  • Creating a .env.example, adding .env to .gitignore, and documenting secret management steps
  • Reviewing a pull request to enforce commit message style and ensure dependency changes are justified
  • Adding a changelog template and a release checklist that links to test coverage and migration steps
  • Defining a simple feature-flag pattern and documenting how to toggle flags safely across environments

FAQ

Does this skill enforce language-specific rules?

It focuses on cross-language conventions (structure, docs, config, secrets) and offers language-specific suggestions where relevant, but not language-exclusive style rules.

How should secrets be stored?

Never commit secrets. Use environment variables, secret managers, or encrypted stores and include a .env.example plus documentation for retrieving secrets securely.

What commit message format do you recommend?

A concise, structured format such as type(scope): short summary (e.g., feat(auth): add JWT refresh) plus an optional longer description in the commit body.