docs: revamp documentation with expanded guides and practical examples

- Rewrite and expand documentation to provide clearer installation and usage instructions
- Add step-by-step setup guide and configuration examples for AI providers
- Introduce advanced options and custom commit templates with practical usage examples
- Provide multiple input/output examples for typical commit scenarios, including multilingual and template-based commits
- Add troubleshooting section covering common edge cases such as missing API keys, file exclusions, and network proxies
- Remove outdated and redundant sections to improve readability and focus on actionable guidance

Signed-off-by: Bo-Yi Wu <[email protected]>

Author: appleboy

skills/commit-helper/SKILL.md

@@ -1,162 +1,258 @@
 ---
 name: generating-commit-messages
-description: This skill provides AI-powered git commit message generation using the `codegpt commit` command. It analyzes git diffs and automatically generates conventional commit messages in multiple languages.
+description: Automatically generates conventional commit messages by analyzing your staged git changes using AI. Use this skill when you need to create well-formatted, meaningful commit messages that follow the Conventional Commits specification, or when you want to save time writing commit descriptions for your changes.
 ---
 
 # Generating Commit Messages
 
-## Description
+## Step-by-Step Instructions
 
-The git-commit skill leverages various AI providers (OpenAI, Anthropic, Gemini, Ollama, Groq, OpenRouter) to automatically generate meaningful commit messages that follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+### Installation
 
-## Installation
+1. Run the install script to download and set up CodeGPT:
 
-Run the install script to automatically download and set up the latest release:
+   ```bash
+   bash < <(curl -sSL https://raw.githubusercontent.com/appleboy/CodeGPT/main/install.sh)
+   ```
 
-```sh
-bash < <(curl -sSL https://raw.githubusercontent.com/appleboy/CodeGPT/main/install.sh)
-```
+2. Configure your AI provider in `~/.config/codegpt/.codegpt.yaml`:
 
-## Usage
+   ```yaml
+   openai:
+     provider: openai # or: azure, anthropic, gemini, ollama, groq, openrouter
+     api_key: your_api_key_here
+     model: gpt-4o
+   ```
 
 ### Basic Usage
 
-Generate a commit message for staged changes (Skip confirmation prompts):
+1. Stage your changes:
+
+   ```bash
+   git add <files>
+   ```
+
+2. Generate and commit with AI-generated message:
+
+   ```bash
+   codegpt commit --no_confirm
+   ```
+
+3. Or preview the message before committing:
+
+   ```bash
+   codegpt commit --preview
+   ```
+
+### Advanced Options
+
+- **Set language**: Use `--lang` to specify output language (en, zh-tw, zh-cn)
+
+  ```bash
+  codegpt commit --lang zh-tw
+  ```
+
+- **Use specific model**: Override the default model
+
+  ```bash
+  codegpt commit --model gpt-4o
+  ```
+
+- **Exclude files**: Ignore certain files from the diff analysis
+
+  ```bash
+  codegpt commit --exclude_list "*.lock,*.json"
+  ```
+
+- **Custom templates**: Format messages according to your team's style
+
+  ```bash
+  codegpt commit --template_string "[{{.summarize_prefix}}] {{.summarize_title}}"
+  ```
+
+- **Amend commit**: Update the previous commit message
+
+  ```bash
+  codegpt commit --amend
+  ```
+
+## Examples of Inputs and Outputs
+
+### Example 1: Adding a new feature
+
+**Input:**
 
 ```bash
+# After making changes to add user authentication
+git add src/auth.go src/middleware.go
 codegpt commit --no_confirm
 ```
 
-### Common Options
+**Output:**
+
+```txt
+feat: add user authentication middleware
+
+Implement JWT-based authentication system with login and token validation
+middleware for protecting API endpoints.
+```
+
+### Example 2: Fixing a bug
+
+**Input:**
 
 ```bash
-# Preview commit message before committing
+# After fixing a null pointer error
+git add src/handlers/user.go
 codegpt commit --preview
+```
 
-# Skip confirmation prompts
-codegpt commit --no_confirm
+**Output:**
 
-# Set output language (en, zh-tw, zh-cn)
-codegpt commit --lang zh-tw
+```txt
+fix: resolve null pointer exception in user handler
 
-# Use specific AI model
-codegpt commit --model gpt-4o
+Add nil checks before accessing user object properties to prevent crashes
+when processing requests with missing user data.
 
-# Amend previous commit
-codegpt commit --amend
+[Preview shown, waiting for confirmation...]
+```
 
-# Display prompt only (no API call)
-codegpt commit --prompt_only
+### Example 3: Chinese language commit
 
-# Write to specific output file
-codegpt commit --file /path/to/commit-msg
+**Input:**
 
-# Customize diff context lines
-codegpt commit --diff_unified 5
+```bash
+git add docs/README.md
+codegpt commit --lang zh-tw --no_confirm
+```
 
-# Exclude specific files from diff
-codegpt commit --exclude_list "*.lock,*.json"
+**Output:**
 
-# Use custom template file
-codegpt commit --template_file ./my-template.tmpl
+```txt
+docs: 更新專案說明文件
 
-# Use inline template string
-codegpt commit --template_string "{{.summarize_prefix}}: {{.summarize_title}}"
+新增安裝步驟說明以及使用範例，讓新使用者能夠快速上手。
+```
 
-# Set API timeout
-codegpt commit --timeout 60s
+### Example 4: Custom template with ticket number
 
-# Configure network proxy
-codegpt commit --proxy http://proxy.example.com:8080
-codegpt commit --socks socks5://127.0.0.1:1080
+**Input:**
+
+```bash
+git add src/api/payment.go
+codegpt commit --template_string "{{.summarize_prefix}}(JIRA-123): {{.summarize_title}}" --no_confirm
 ```
 
-### Template Variables
+**Output:**
 
-When using custom templates, the following variables are available:
+```txt
+feat(JIRA-123): integrate payment gateway API
+```
 
-- `{{.summarize_prefix}}` - Conventional commit prefix (feat, fix, docs, etc.)
-- `{{.summarize_title}}` - Brief commit title
-- `{{.summarize_message}}` - Detailed commit message body
+### Example 5: Excluding lock files
 
-You can also provide custom variables:
+**Input:**
 
 ```bash
-codegpt commit --template_vars "author=John,ticket=PROJ-123"
-codegpt commit --template_vars_file ./vars.env
+git add .
+codegpt commit --exclude_list "package-lock.json,yarn.lock,go.sum" --preview
 ```
 
-## Workflow
+**Output:**
 
-1. **Diff Analysis**: Analyzes staged changes using `git diff`
-2. **Summarization**: AI generates a summary of the changes
-3. **Title Generation**: Creates a concise commit title
-4. **Prefix Detection**: Determines appropriate conventional commit prefix
-5. **Message Composition**: Combines all elements into a formatted message
-6. **Translation** (optional): Translates to target language if specified
-7. **Preview & Confirmation**: Shows message for review and optional editing
-8. **Commit**: Records changes to the repository
+```txt
+refactor: reorganize project structure
 
-## Configuration
+Move utility functions into separate packages and update import paths
+throughout the codebase for better modularity.
 
-Configure via `~/.config/codegpt/.codegpt.yaml`:
+(Lock files excluded from analysis)
+```
 
-```yaml
-openai:
-  provider: openai  # or: azure, anthropic, gemini, ollama, groq, openrouter
-  api_key: your_api_key_here
-  model: gpt-4o
-  timeout: 30s
+## Common Edge Cases
 
-git:
-  diff_unified: 3
-  exclude_list: []
-  template_file: ""
-  template_string: ""
+### No staged changes
 
-output:
-  lang: en  # or: zh-tw, zh-cn
-  file: ""
+**Issue**: Running `codegpt commit` without staging any changes.
+
+**Solution**: Stage your changes first:
+
+```bash
+git add <files>
+codegpt commit
 ```
 
-## Examples
+### API timeout for large diffs
+
+**Issue**: Large changesets may cause API timeouts.
 
-### Example 1: Basic commit without preview
+**Solution**: Increase timeout or commit changes in smaller batches:
 
 ```bash
-# Stage your changes
-git add .
+codegpt commit --timeout 60s
+```
 
-# Generate commit message without confirmation
-codegpt commit --no_confirm
+### Generated files in diff
+
+**Issue**: Lock files or generated code affecting commit message quality.
+
+**Solution**: Exclude these files from analysis:
+
+```bash
+codegpt commit --exclude_list "package-lock.json,yarn.lock,*.min.js,dist/*"
 ```
 
-### Example 2: Chinese commit message
+### API key not configured
+
+**Issue**: Error message about missing API key.
+
+**Solution**: Set up your API key in the config file:
 
 ```bash
-codegpt commit --lang zh-tw --model gpt-4o --no_confirm
+codegpt config set openai.api_key "your-api-key-here"
 ```
 
-### Example 3: Custom template
+### Custom commit format required
+
+**Issue**: Team requires specific commit message format (e.g., with ticket numbers).
+
+**Solution**: Use custom templates:
 
 ```bash
-codegpt commit \
-  --template_string "[{{.summarize_prefix}}] {{.summarize_title}}" \
-  --template_vars "ticket=PROJ-123"
+codegpt commit --template_string "[{{.summarize_prefix}}] TICKET-123: {{.summarize_title}}"
 ```
 
-### Example 4: With file exclusions
+Or save it in config file:
+
+```yaml
+git:
+  template_string: "[{{.summarize_prefix}}] {{.ticket}}: {{.summarize_title}}"
+```
+
+### Multilingual team
+
+**Issue**: Need commit messages in different languages for different repositories.
+
+**Solution**: Set language per command or configure per repository:
 
 ```bash
-codegpt commit \
-  --exclude_list "package-lock.json,yarn.lock,go.sum" \
-  --preview
+# Per command
+codegpt commit --lang zh-cn
+
+# Or set in repository's .codegpt.yaml
+output:
+  lang: zh-cn
 ```
 
-## Tips
+### Network proxy required
+
+**Issue**: API calls fail due to corporate firewall.
 
-1. **Stage Changes First**: Always run `git add` before using `codegpt commit`
-2. **Use Preview Mode**: Review messages with `--preview` before committing
-3. **Customize Templates**: Create templates that match your team's commit style
-4. **Set Default Language**: Configure your preferred language in config file
-5. **Exclude Generated Files**: Use `--exclude_list` to ignore lock files and generated code
+**Solution**: Configure proxy settings:
+
+```bash
+codegpt commit --proxy http://proxy.company.com:8080
+# Or for SOCKS proxy
+codegpt commit --socks socks5://127.0.0.1:1080
+```