Initial commit
This commit is contained in:
Zhongwei Li
145
skills/git-commit-messages/SKILL.md
Normal file
145
skills/git-commit-messages/SKILL.md
Normal file
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: git-commit-messages
|
||||
description: Format git commit messages correctly, avoiding HEREDOC syntax issues in favor of multiline strings
|
||||
---
|
||||
|
||||
# Git Commit Message Formatting
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when creating git commits with the Bash tool, especially for commits with:
|
||||
|
||||
- Multi-line messages
|
||||
- Body text or explanations
|
||||
- Co-authored-by footers
|
||||
- Claude Code attribution
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Avoid HEREDOC syntax** - Use `-m` with multiline strings instead.
|
||||
|
||||
## Pattern to Follow
|
||||
|
||||
### ✅ DO - Use multiline string with -m
|
||||
|
||||
```bash
|
||||
git commit -m "feat(github): add github plugin
|
||||
|
||||
This adds comprehensive GitHub workflow support including
|
||||
commands for PR management and review workflows.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
**Key points:**
|
||||
|
||||
- Single `-m` flag with entire message in quotes
|
||||
- Newlines preserved within the quoted string
|
||||
- No special syntax or escaping needed
|
||||
- Works reliably across all environments
|
||||
|
||||
### ❌ DON'T - Use HEREDOC syntax
|
||||
|
||||
```bash
|
||||
# This FAILS in Claude Code's Bash tool
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(github): add github plugin
|
||||
|
||||
This adds comprehensive GitHub workflow support.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
**Why this fails:**
|
||||
|
||||
- HEREDOC syntax has shell interpretation issues
|
||||
- Fails in certain execution contexts
|
||||
- More complex than necessary
|
||||
- Unreliable across environments
|
||||
|
||||
## Examples
|
||||
|
||||
### Simple commit
|
||||
|
||||
```bash
|
||||
git commit -m "fix: resolve path configuration issue"
|
||||
```
|
||||
|
||||
### Commit with body
|
||||
|
||||
```bash
|
||||
git commit -m "feat: add progressive disclosure pattern
|
||||
|
||||
Skills now support references/ subdirectory for
|
||||
detailed documentation that loads on-demand."
|
||||
```
|
||||
|
||||
### Commit with footer
|
||||
|
||||
```bash
|
||||
git commit -m "chore: update dependencies
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
### Full conventional commit
|
||||
|
||||
```bash
|
||||
git commit -m "feat(tools): add git commit message skill
|
||||
|
||||
This skill teaches Claude to format git commit messages
|
||||
using multiline strings instead of HEREDOC syntax, which
|
||||
fails in certain shell environments.
|
||||
|
||||
The pattern uses a single -m flag with the entire message
|
||||
in quotes, preserving newlines naturally.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
## Why It Matters
|
||||
|
||||
Using `-m` with multiline strings is:
|
||||
|
||||
- **Reliable:** Works consistently in all environments
|
||||
- **Simple:** No complex shell syntax needed
|
||||
- **Portable:** Standard git behavior
|
||||
- **Direct:** Git handles newlines correctly
|
||||
|
||||
HEREDOC syntax causes issues because:
|
||||
|
||||
- Shell interpretation varies by environment
|
||||
- Execution context in Claude Code differs from terminal
|
||||
- Quote handling becomes complex
|
||||
- Unnecessary complexity for the task
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Template for commits with Claude Code attribution:**
|
||||
|
||||
```bash
|
||||
git commit -m "<type>[optional scope]: <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
**Remember:**
|
||||
|
||||
- One `-m` flag
|
||||
- Entire message in double quotes
|
||||
- Newlines work naturally
|
||||
- No HEREDOC needed
|
||||
209
skills/git-directory-management/SKILL.md
Normal file
209
skills/git-directory-management/SKILL.md
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
name: git-directory-management
|
||||
description: Manage git-tracked directories correctly - never create .gitkeep files in directories that will immediately contain tracked files
|
||||
---
|
||||
|
||||
# Git Directory Management
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when creating new directories in a git repository, especially when:
|
||||
|
||||
- Setting up project structure
|
||||
- Creating plugin/package directories
|
||||
- Organizing code into new folders
|
||||
- Adding configuration directories
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Never create `.gitkeep` files in directories you're about to populate with tracked files.**
|
||||
|
||||
`.gitkeep` is ONLY for keeping truly empty directories in version control.
|
||||
|
||||
## Pattern to Follow
|
||||
|
||||
### ✅ DO - Add actual files directly
|
||||
|
||||
```bash
|
||||
# Create directory and add actual file
|
||||
mkdir -p plugins/new-plugin/skills
|
||||
# Now add your actual files
|
||||
# (Write SKILL.md, plugin.json, etc.)
|
||||
```
|
||||
|
||||
**Key points:**
|
||||
|
||||
- Git automatically tracks directories when they contain files
|
||||
- Empty directory + file creation can happen in one step
|
||||
- No `.gitkeep` needed - the real files track the directory
|
||||
|
||||
### ❌ DON'T - Create .gitkeep then immediately add files
|
||||
|
||||
```bash
|
||||
# This is wasteful and wrong
|
||||
mkdir -p plugins/new-plugin/skills
|
||||
touch plugins/new-plugin/skills/.gitkeep # ❌ Unnecessary!
|
||||
git add plugins/new-plugin/skills/.gitkeep
|
||||
git commit -m "Add empty directory"
|
||||
|
||||
# Then immediately add real files
|
||||
# (Write SKILL.md)
|
||||
git add plugins/new-plugin/skills/
|
||||
git commit -m "Add actual skill"
|
||||
```
|
||||
|
||||
**Why this is wrong:**
|
||||
|
||||
- `.gitkeep` serves no purpose if files are coming
|
||||
- Creates unnecessary commits
|
||||
- Clutters directory with placeholder file
|
||||
- Extra file to maintain/remove later
|
||||
|
||||
## When to Use .gitkeep
|
||||
|
||||
`.gitkeep` is appropriate ONLY when:
|
||||
|
||||
1. **The directory must exist but remain empty**
|
||||
2. **The empty directory is required for the application to function**
|
||||
3. **No files will be added to the directory immediately**
|
||||
|
||||
**Valid use case example:**
|
||||
|
||||
```bash
|
||||
# Application requires logs/ directory to exist on startup
|
||||
mkdir -p logs
|
||||
touch logs/.gitkeep
|
||||
git add logs/.gitkeep
|
||||
git commit -m "chore: add logs directory for runtime output"
|
||||
```
|
||||
|
||||
**Why this is valid:**
|
||||
|
||||
- Directory must exist before application runs
|
||||
- Directory will be populated at runtime (not in version control)
|
||||
- `.gitkeep` ensures the empty directory is tracked
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario: Creating a new plugin structure
|
||||
|
||||
✅ **DO:**
|
||||
|
||||
```bash
|
||||
mkdir -p plugins/new-plugin/{skills,commands}
|
||||
# Then immediately create your files:
|
||||
# Write plugins/new-plugin/.claude-plugin/plugin.json
|
||||
# Write plugins/new-plugin/skills/skill-name/SKILL.md
|
||||
# Write plugins/new-plugin/README.md
|
||||
# Add all files in one commit
|
||||
git add plugins/new-plugin/
|
||||
git commit -m "feat: add new-plugin"
|
||||
```
|
||||
|
||||
❌ **DON'T:**
|
||||
|
||||
```bash
|
||||
mkdir -p plugins/new-plugin/skills
|
||||
touch plugins/new-plugin/skills/.gitkeep # ❌ Wrong!
|
||||
# Then add real files later
|
||||
```
|
||||
|
||||
### Scenario: Creating empty directories for runtime
|
||||
|
||||
✅ **DO:**
|
||||
|
||||
```bash
|
||||
mkdir -p tmp/cache
|
||||
touch tmp/cache/.gitkeep
|
||||
git add tmp/cache/.gitkeep
|
||||
git commit -m "chore: add cache directory for runtime"
|
||||
```
|
||||
|
||||
**Why this is correct:** Cache directory must exist but contents are not tracked.
|
||||
|
||||
### Scenario: Setting up tool configuration directories
|
||||
|
||||
✅ **DO:**
|
||||
|
||||
```bash
|
||||
mkdir -p .config/tool
|
||||
# Immediately add configuration file
|
||||
# Write .config/tool/config.json
|
||||
git add .config/tool/config.json
|
||||
git commit -m "feat: add tool configuration"
|
||||
```
|
||||
|
||||
❌ **DON'T:**
|
||||
|
||||
```bash
|
||||
mkdir -p .config/tool
|
||||
touch .config/tool/.gitkeep # ❌ Wrong! You're about to add config.json
|
||||
```
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```text
|
||||
Creating a new directory?
|
||||
│
|
||||
├─ Will you add tracked files immediately?
|
||||
│ └─ YES → No .gitkeep needed, just add the files
|
||||
│
|
||||
└─ Will the directory stay empty in version control?
|
||||
│
|
||||
├─ YES, and it must exist → Use .gitkeep
|
||||
│
|
||||
└─ NO, files coming later → Wait until files exist, then commit
|
||||
```
|
||||
|
||||
## Why It Matters
|
||||
|
||||
**Benefits of not using .gitkeep unnecessarily:**
|
||||
|
||||
- Cleaner repository (fewer placeholder files)
|
||||
- Fewer commits (one commit with actual content)
|
||||
- No cleanup needed later (no .gitkeep to remove)
|
||||
- Clear intent (tracked files show directory purpose)
|
||||
|
||||
**Problems with unnecessary .gitkeep:**
|
||||
|
||||
- Clutters directories with meaningless files
|
||||
- Creates confusing git history (empty → populated)
|
||||
- Requires eventual cleanup
|
||||
- Adds maintenance burden
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Rule of thumb:**
|
||||
|
||||
- **About to add files?** → No `.gitkeep`
|
||||
- **Directory stays empty?** → Use `.gitkeep`
|
||||
- **Not sure yet?** → Wait until files exist
|
||||
|
||||
**Remember:**
|
||||
|
||||
- Git tracks directories through their files
|
||||
- `.gitkeep` is for truly empty directories
|
||||
- One commit with actual content beats two commits (empty + populated)
|
||||
- When in doubt, add the real files first
|
||||
|
||||
## Examples in This Repository
|
||||
|
||||
**Correct usage (runtime directories):**
|
||||
|
||||
- None currently - all directories contain tracked files
|
||||
|
||||
**What NOT to do:**
|
||||
|
||||
```bash
|
||||
# ❌ DON'T create .gitkeep in plugins/tools/skills/
|
||||
# This directory is meant to contain skills, not stay empty
|
||||
```
|
||||
|
||||
**Correct approach:**
|
||||
|
||||
```bash
|
||||
# ✅ Just add your skill directly
|
||||
# Write plugins/tools/skills/new-skill/SKILL.md
|
||||
git add plugins/tools/skills/new-skill/
|
||||
git commit -m "feat(tools): add new-skill"
|
||||
```
|
||||
48
skills/skill-rules.json
Normal file
48
skills/skill-rules.json
Normal file
@@ -0,0 +1,48 @@
|
||||
{
|
||||
"description": "Skill activation rules for tools plugin",
|
||||
"skills": {
|
||||
"tools@boneskull-plugins:git-commit-messages": {
|
||||
"type": "guardrail",
|
||||
"enforcement": "suggest",
|
||||
"priority": "high",
|
||||
"description": "Format git commit messages correctly using multiline strings instead of HEREDOC",
|
||||
"promptTriggers": {
|
||||
"keywords": [
|
||||
"git commit",
|
||||
"commit message",
|
||||
"create commit",
|
||||
"commit changes",
|
||||
"commit with message"
|
||||
],
|
||||
"intentPatterns": [
|
||||
"(create|make|add|write).*commit",
|
||||
"commit.*message",
|
||||
"(how to|how do I).*commit"
|
||||
]
|
||||
}
|
||||
},
|
||||
"tools@boneskull-plugins:git-directory-management": {
|
||||
"type": "guardrail",
|
||||
"enforcement": "block",
|
||||
"priority": "critical",
|
||||
"description": "Prevent unnecessary .gitkeep files in directories that will contain tracked files",
|
||||
"promptTriggers": {
|
||||
"keywords": [
|
||||
".gitkeep",
|
||||
"git keep",
|
||||
"track empty directory",
|
||||
"keep directory in git",
|
||||
"empty directory git"
|
||||
],
|
||||
"intentPatterns": [
|
||||
"create.*\\.gitkeep",
|
||||
"add.*\\.gitkeep",
|
||||
"(track|keep).*empty.*dir",
|
||||
"git.*track.*directory"
|
||||
]
|
||||
},
|
||||
"blockMessage": "⚠️ BLOCKED - .gitkeep Anti-Pattern Detected\n\n📋 REQUIRED ACTION:\n1. Use Skill tool: 'tools@boneskull-plugins:git-directory-management'\n2. Review when .gitkeep is actually needed (rarely!)\n3. Add actual files instead of .gitkeep\n\nReason: .gitkeep is ONLY for truly empty directories.\nIf you're about to add files, just add them directly.\n\n💡 TIP: Git tracks directories automatically when they contain files"
|
||||
}
|
||||
},
|
||||
"version": "1.0"
|
||||
}
|
||||
Reference in New Issue
Block a user