home / skills / joncrangle / .dotfiles / git-standards

git-standards skill

safe

/dot_config/opencode/skills/git-standards

This skill enforces safe git practices and conventional commits, guiding you to create meaningful PRs and prevent secret leaks.

npx playbooks add skill joncrangle/.dotfiles --skill git-standards

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

Files (1)

SKILL.md

1.4 KB

---
name: git-standards
description: This skill should be used when the user asks to "commit changes", "create a PR", "push code", "check git status", or "review git history". Enforces safety checks and conventional commits.
---

<skill_doc>
# Git Standards & Protocols

## 🛑 SAFETY CHECKS (Critical)
**Tool Enforcement**:
Use the `git_safe` tool for all git operations (status, diff, log, add, commit, push).

**Manual Agent Checks**:
Before ANY commit, scan staged files using `git_safe(action: "diff", target: "--cached")` for:
- **Secrets**: `.env`, `*_KEY`, `*_SECRET`, `password`, `token`.
- **Large Files**: Anything >10MB or binary files.
- **Build Artifacts**: `dist/`, `node_modules/`, `.DS_Store`.
**Action**: If found, UNSTAGE immediately and warn user.

## 📝 Commit Protocol (Conventional)
Format: `<type>(<scope>): <description>`

| Type | Meaning |
| :--- | :--- |
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `refactor` | Code change (no feature/fix) |
| `perf` | Performance improvement |
| `test` | Adding/fixing tests |
| `chore` | Build/auxiliary tools |

**Examples**:
- `feat(auth): add google oauth provider`
- `fix(login): handle null session token`

## 🚀 PR Protocol
**Title**: Matches commit format.
**Body**:
```markdown
## Why
(Context/Problem)

## What
(Summary of changes)

## Verification
- [ ] Tests
- [ ] Manual Check
```
</skill_doc>

Overview

This skill enforces safe, consistent Git workflows for committing, pushing, and creating pull requests. It runs automated safety checks to prevent secrets, large files, or build artifacts from being committed and guides users to write Conventional Commits and structured PRs. Use it whenever you interact with Git to maintain repository hygiene and clear history.

How this skill works

All git operations are performed through the git_safe tool to ensure controlled actions (status, diff, log, add, commit, push). Before any commit, the skill inspects staged changes via git_safe(action: "diff", target: "--cached") to detect secrets, large/binary files, and common build artifacts and will unstage and warn when problems are found. It enforces a Conventional Commit format and produces a PR title/body template that includes Why, What, and Verification sections.

When to use it

When you want to commit staged changes or run git status/diff/log
Before creating a pull request or pushing code to a remote
When reviewing git history to ensure commit message consistency
When you need to enforce repository safety checks for secrets and large files
When preparing a PR that needs a clear title and verification checklist

Best practices

Always run git operations through git_safe to apply checks and logging
Scan staged changes for secrets (.env, *_KEY, *_SECRET, password, token) and unstage any matches immediately
Reject or remove large (>10MB) and binary files from commits; use LFS if needed
Avoid committing build artifacts (dist/, node_modules/, .DS_Store); add them to .gitignore
Use Conventional Commit format: type(scope): description and keep descriptions concise
Populate PR body with Why, What, and Verification checkboxes before opening

Example use cases

Commit a set of dotfile updates while ensuring no API keys or .env content are included
Create a PR for a Neovim configuration change with a matching Conventional Commit title
Run git status and git log through the safe tool to review staged changes and history
Push install scripts only after automatic checks remove build artifacts and large files
Review repository history to refactor commit messages into consistent Conventional format

FAQ

What happens if a secret is detected in staged files?

The skill will unstage the offending files, warn you about the secret, and advise removing or rotating the secret before recommitting.

How should I format commit messages?

Use Conventional Commits: type(scope): short description, where type is feat, fix, docs, refactor, perf, test, or chore.