ajet/gong-fu-cha
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Gong Fu Cha - Tea CLI skills for Claude Code

Browse Source 
Add comprehensive Claude Code skills for Gitea's tea CLI tool.

Includes:
- Complete skill documentation (skills/SKILL.md)
- Detailed examples (skills/examples.md)
- User-facing README with installation and usage
- Claude Code instructions (CLAUDE.md)
- Git ignore file

🍵 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Adam Jeniski 2026-01-05 18:52:02 -05:00
commit 42d7b43705
5 changed files with 1149 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
.gitignore vendored Normal file
View File

@ -0,0 +1,13 @@
# Editor
.vscode/
.idea/
*.swp
*.swo
*~
# OS
.DS_Store
Thumbs.db
# Logs
*.log

226
CLAUDE.md Normal file
View File

@ -0,0 +1,226 @@
# CLAUDE.md
This file provides guidance to Claude Code when working with the Gong Fu Cha repository.
## Repository Purpose
This repository provides Claude Code skills for working with Gitea's `tea` CLI tool. The skills enable seamless interaction with Gitea repositories (like git.ajet.fyi) directly through Claude Code conversations.
## Repository Structure
- **skills/SKILL.md** - Main Claude Code skill definition for the `tea` CLI
- **README.md** - User-facing documentation
- **CLAUDE.md** - This file (Claude Code instructions)
## Tea CLI Overview
The `tea` command-line tool is Gitea's official CLI for interacting with Gitea instances. It provides comprehensive functionality for:
- **Pull Requests**: Create, review, merge, checkout
- **Issues**: Create, edit, close, reopen
- **Releases**: Create, edit, delete, manage assets
- **Labels & Milestones**: Manage project organization
- **Comments**: Add comments to issues/PRs
- **Repositories**: Clone, view details
- **Notifications**: Check and manage notifications
## Key Commands
### Context Detection
Tea automatically detects repository context from the current working directory. It reads `.git/config` to determine the Gitea remote and repository.
### Authentication
Tea uses stored credentials in `$XDG_CONFIG_HOME/tea` (usually `~/.config/tea`). Check authentication with:
```bash
tea whoami
```
### Common Operations
**Pull Requests:**
```bash
tea pr ls # List PRs
tea pr create -t "Title" -d "Description" # Create PR
tea pr checkout 42 # Checkout PR locally
tea pr approve 42 # Approve PR
tea pr merge 42 # Merge PR
```
**Issues:**
```bash
tea issues ls # List issues
tea issues create -t "Title" -d "Body" # Create issue
tea issues close 42 # Close issue
```
**Releases:**
```bash
tea releases ls # List releases
tea releases create --tag v1.0.0 -t "v1.0.0" -n "Release notes"
```
## Important Notes for Claude Code
### Always Check Authentication First
Before running `tea` commands, verify the user is logged in:
```bash
tea whoami
```
If not authenticated, guide the user to run:
```bash
tea login add --url https://git.ajet.fyi
```
### Repository Context
Tea works best when run from within a git repository directory. If tea commands fail with "no repository found", ensure:
1. You're in a git repository directory
2. The repository has a Gitea remote configured
3. Or use `--repo owner/repo` flag to specify repository explicitly
### Output Formats
Tea supports multiple output formats. For machine-readable output, use:
```bash
tea pr ls --output json
tea issues ls -o yaml
```
For user-friendly output, use the default table format or specify:
```bash
tea pr ls --output table
```
### Error Handling
Common errors:
- **"Login not found"**: User needs to run `tea login add`
- **"Repository not found"**: Check repository context or use `--repo` flag
- **"Token expired"**: User needs to refresh OAuth token: `tea login oauth-refresh`
- **"Permission denied"**: Token lacks required scopes
### Help and Documentation
- Use `tea --help` for general help
- Use `tea <command> --help` for command-specific help
- Use `tea man` for comprehensive manual pages
## Development Workflow Integration
### Creating PRs
When helping users create PRs:
1. Ensure changes are committed and pushed
2. Determine base and head branches
3. Generate meaningful PR title and description
4. Use `tea pr create` with appropriate flags
Example:
```bash
tea pr create --title "Feature: Add new capability" \
--description "Detailed description of changes" \
--base main \
--head feature-branch
```
### Managing Issues
When helping users manage issues:
1. List existing issues to check for duplicates
2. Create issues with descriptive titles and labels
3. Link issues to PRs when relevant
Example:
```bash
tea issues create \
--title "Bug: Fix authentication flow" \
--description "Detailed description" \
--labels bug,priority
```
### Release Management
When helping users create releases:
1. Verify the tag doesn't exist
2. Generate release notes from commits
3. Include relevant assets if needed
Example:
```bash
tea releases create \
--tag v1.0.0 \
--title "Version 1.0.0" \
--note "Release notes here" \
--asset ./binary
```
## Best Practices
1. **Always verify repository context** before running tea commands
2. **Check authentication status** with `tea whoami` first
3. **Use descriptive titles and descriptions** for PRs and issues
4. **Apply relevant labels** to improve organization
5. **Check for duplicates** before creating issues
6. **Use appropriate merge strategies** (merge, squash, rebase)
7. **Clean up branches** after merging PRs
## Integration with Other Tools
Tea works well with:
- **git**: For local repository operations
- **gh** (GitHub CLI): Similar workflow for GitHub repos
- **commitly**: For managing commits across multiple repos
## Skill Usage
The `/tea` skill can be invoked explicitly, but Claude Code should also recognize tea-related requests naturally:
- "Create a PR for my changes"
- "List open issues"
- "Review PR #42"
- "Create a release"
Claude should automatically use the tea skill when appropriate for Gitea operations.
## Extending the Skills
When adding new examples or workflows:
1. Test the commands manually first
2. Add to the appropriate section in `skills/SKILL.md`
3. Include both basic and advanced examples
4. Document any prerequisites or gotchas
5. Update this CLAUDE.md if needed
## Common Pitfalls
- **Not in repo directory**: Many tea commands require repository context
- **Missing authentication**: Always check `tea whoami` first
- **Wrong remote**: Tea looks for Gitea remotes, not GitHub/GitLab
- **Insufficient token permissions**: Token needs appropriate scopes
- **Branch not pushed**: Can't create PR for unpushed branches
## Testing
When testing tea commands:
1. Use a test repository when possible
2. Verify authentication first
3. Check repository context
4. Test with dry-run flags when available
5. Verify output format matches expectations

172
README.md Normal file
View File

@ -0,0 +1,172 @@
# Gong Fu Cha 🍵
**Gong Fu Cha** (工夫茶) - The art of making tea with skill.
This repository provides Claude Code skills for working with Gitea's `tea` CLI tool, enabling seamless interaction with Gitea repositories directly from your terminal through Claude Code.
## What is Tea?
[Tea](https://gitea.com/gitea/tea) is the official command-line tool for Gitea. It allows you to:
- Create and manage pull requests
- Create and manage issues
- Review code
- Create releases
- Manage labels and milestones
- Clone repositories
- And much more!
## Installation
### Install Tea CLI
**macOS (Homebrew):**
```bash
brew tap gitea/tap
brew install tea
```
**Linux:**
```bash
# Download latest release from https://gitea.com/gitea/tea/releases
# Or use your package manager
```
**From source:**
```bash
go install gitea.com/gitea/tea@latest
```
### Setup Tea
Login to your Gitea instance:
```bash
tea login add --url https://git.ajet.fyi
```
Or use a token:
```bash
tea login add --url https://git.ajet.fyi --token YOUR_TOKEN
```
Verify your login:
```bash
tea whoami
```
## Claude Code Skills
This repository provides a comprehensive Claude Code skill for the `tea` CLI.
### Installing the Skill
The skill is located in the `skills/` directory. To use it with Claude Code:
1. This repository should be in your Claude Code skills directory, or
2. Symlink the skills directory to `~/.claude/skills/tea`:
```bash
ln -s /path/to/gong-fu-cha/skills ~/.claude/skills/tea
```
### Using the Skill
Once installed, you can invoke the skill in Claude Code with:
```
/tea
```
Or simply ask Claude to perform Gitea operations:
- "Create a PR for this branch"
- "List open issues"
- "Review PR #42"
- "Create a release tagged v1.0.0"
## Common Tea Commands
### Pull Requests
```bash
# List PRs
tea pr ls
# Create a PR
tea pr create -t "Title" -d "Description"
# Review a PR
tea pr checkout 42
tea pr approve 42
tea pr merge 42
```
### Issues
```bash
# List issues
tea issues ls
# Create an issue
tea issues create -t "Bug: Fix something" -d "Details"
# Close an issue
tea issues close 42
```
### Releases
```bash
# List releases
tea releases ls
# Create a release
tea releases create --tag v1.0.0 -t "Version 1.0.0" -n "Release notes"
```
## Documentation
- **Tea Manual**: Run `tea man` for comprehensive documentation
- **Command Help**: Run `tea <command> --help` for command-specific help
- **Skill Documentation**: See `skills/SKILL.md` for Claude Code integration details
## Repository Structure
```
gong-fu-cha/
├── skills/
│ └── SKILL.md # Claude Code skill definition
├── README.md # This file
└── CLAUDE.md # Instructions for Claude Code
```
## Why "Gong Fu Cha"?
Gong Fu Cha (工夫茶) is a traditional Chinese tea ceremony that emphasizes skill, attention to detail, and the artful preparation of tea. Just as Gong Fu Cha is about mastering the art of tea, this repository is about mastering the art of using `tea` - the Gitea CLI tool - with skill and efficiency through Claude Code.
The name is also a play on words:
- **Tea** = The CLI tool for Gitea
- **Gong Fu** (功夫) = Skill, mastery, kung fu
- **Cha** (茶) = Tea
Perfect harmony! 🍵✨
## License
MIT
## Contributing
Contributions welcome! Feel free to:
- Add new examples to the skill documentation
- Improve existing documentation
- Add new workflows
- Report issues
## Links
- [Gitea Tea CLI](https://gitea.com/gitea/tea)
- [Gitea Documentation](https://docs.gitea.io/)
- [Claude Code](https://claude.ai/code)

334
skills/SKILL.md Normal file
View File

@ -0,0 +1,334 @@
---
name: tea
description: Use Gitea's tea CLI to manage issues, PRs, releases, and other repository operations. Works with git.ajet.fyi and other Gitea instances.
---
# Gitea Tea CLI
## When to Use This Skill
Use this skill when you need to:
- **Create or manage pull requests** without leaving the terminal
- **Create, update, or close issues**
- **Review pull requests** and approve/reject changes
- **Create releases** and manage release assets
- **Manage labels and milestones**
- **Check notifications** from Gitea
- **Clone repositories** from Gitea instances
## How It Works
The `tea` CLI tool interacts directly with Gitea instances via their API. It automatically detects repository context from your current directory and uses stored login credentials.
## Setup
### Check if logged in
```bash
tea whoami
```
### Login to a Gitea instance
```bash
tea login add --url https://git.ajet.fyi --token YOUR_TOKEN
```
Or use interactive OAuth:
```bash
tea login add --url https://git.ajet.fyi --oauth
```
### List configured logins
```bash
tea login ls
```
## Common Operations
### Pull Requests
**List PRs:**
```bash
tea pr ls
tea pr ls --state open
tea pr ls --state closed
```
**Create a PR:**
```bash
tea pr create --title "Feature: Add new capability" --description "Detailed description"
tea pr create -t "Title" -d "Description" --base main --head feature-branch
```
**View PR details:**
```bash
tea pr <number>
tea pr 42 --comments
```
**Checkout a PR locally:**
```bash
tea pr checkout 42
tea pr co 42 --branch # Create local branch
```
**Review a PR:**
```bash
tea pr review 42
tea pr approve 42
tea pr reject 42
```
**Merge a PR:**
```bash
tea pr merge 42
tea pr merge 42 --style squash
tea pr merge 42 --style rebase
```
**Close a PR:**
```bash
tea pr close 42
```
### Issues
**List issues:**
```bash
tea issues ls
tea issues ls --state open
tea issues ls --labels bug,urgent
tea issues ls --milestone v1.0
```
**Create an issue:**
```bash
tea issues create --title "Bug: Something broken" --description "Details here"
tea issues create -t "Title" -d "Description" --labels bug,priority
```
**Edit an issue:**
```bash
tea issues edit 42 --title "New title"
tea issues edit 42 --add-labels bug,urgent
tea issues edit 42 --milestone v1.0
```
**Close/Reopen issues:**
```bash
tea issues close 42
tea issues reopen 42
```
### Comments
**Add a comment to an issue or PR:**
```bash
tea comment 42 "This is my comment"
```
### Releases
**List releases:**
```bash
tea releases ls
```
**Create a release:**
```bash
tea releases create --tag v1.0.0 --title "Version 1.0.0" --note "Release notes here"
tea releases create --tag v1.0.0 -t "v1.0.0" -n "Notes" --asset ./binary
```
**Delete a release:**
```bash
tea releases delete v1.0.0 --confirm
```
### Labels
**List labels:**
```bash
tea labels ls
```
**Create a label:**
```bash
tea labels create --name bug --color "#ff0000" --description "Bug reports"
```
### Milestones
**List milestones:**
```bash
tea milestones ls
tea milestones ls --state open
```
**Create a milestone:**
```bash
tea milestones create --title "v1.0" --description "First release"
tea milestones create -t "v1.0" -d "Description" --deadline 2026-12-31
```
**Add issue to milestone:**
```bash
tea milestones issues add v1.0 42
```
### Repositories
**Show repo details:**
```bash
tea repo
```
**Clone a repository:**
```bash
tea clone owner/repo
tea clone owner/repo --depth 1
```
### Branches
**List branches:**
```bash
tea branches ls
```
### Notifications
**Check notifications:**
```bash
tea notifications
tea notifications --mine
```
### Open in Browser
**Open repo in browser:**
```bash
tea open
tea open 42 # Open issue/PR #42
```
## Context and Options
### Repository Context
Tea automatically detects the repository from your current directory. Override with:
```bash
tea pr ls --repo owner/repo
tea issues create --repo owner/repo -t "Title"
```
### Login Selection
Use a specific Gitea login:
```bash
tea pr ls --login my-gitea
```
### Output Formats
Control output format:
```bash
tea pr ls --output json
tea pr ls --output yaml
tea pr ls --output csv
tea issues ls -o table # Default
```
## Advanced Usage
### Filtering and Searching
**Filter PRs by author:**
```bash
tea pr ls --author username
```
**Search issues by keyword:**
```bash
tea issues ls --keyword "search term"
```
**Filter by labels:**
```bash
tea issues ls --labels bug,urgent
```
**Filter by milestone:**
```bash
tea issues ls --milestone v1.0
```
**Filter by assignee:**
```bash
tea issues ls --assignee username
```
### Pagination
```bash
tea pr ls --page 2
tea pr ls --limit 50
```
## Important Notes
- **Repository context**: Tea works best when run from within a git repository directory
- **Multiple logins**: You can configure multiple Gitea instances
- **Default login**: Set a default login with `tea login default`
- **Token permissions**: Ensure your access token has appropriate scopes
- **Help available**: Run `tea <command> --help` for detailed options
- **Manual pages**: Use `tea man` for comprehensive documentation
## Typical Workflows
### Creating a PR from a feature branch
1. Make changes and commit
2. Push to remote
3. Create PR:
```bash
tea pr create -t "Feature: New capability" -d "Description of changes"
```
4. Wait for review or review yourself
### Reviewing and merging a PR
1. List PRs: `tea pr ls`
2. Checkout locally: `tea pr checkout 42`
3. Test the changes
4. Approve: `tea pr approve 42`
5. Merge: `tea pr merge 42 --style squash`
### Creating a release
1. Ensure you're on the right branch/commit
2. Create release:
```bash
tea releases create --tag v1.0.0 --title "Version 1.0.0" \
--note "Release notes" --asset ./binary
```
### Managing issues
1. List open issues: `tea issues ls --state open`
2. View specific issue: `tea issues 42`
3. Add comment: `tea comment 42 "Working on this"`
4. Close when done: `tea issues close 42`
## Getting Help
```bash
tea --help
tea <command> --help
tea man
```

404
skills/examples.md Normal file
View File

@ -0,0 +1,404 @@
# Tea CLI Examples
Quick reference for common `tea` commands.
## Setup
```bash
# Login to Gitea
tea login add --url https://git.ajet.fyi
# Check who you're logged in as
tea whoami
# List all configured logins
tea login ls
# Set default login
tea login default
```
## Pull Requests
```bash
# List all PRs
tea pr ls
# List open PRs only
tea pr ls --state open
# View specific PR with comments
tea pr 42 --comments
# Create a PR
tea pr create \
--title "Feature: Add authentication" \
--description "Implements JWT authentication" \
--base main \
--head feature/auth
# Create PR with labels and assignee
tea pr create -t "Fix bug" -d "Description" \
--labels bug,urgent \
--assignees username
# Checkout a PR locally
tea pr checkout 42
tea pr co 42 --branch # Create local branch
# Review a PR
tea pr review 42
# Approve a PR
tea pr approve 42
# Request changes
tea pr reject 42
# Merge a PR
tea pr merge 42 # Default merge
tea pr merge 42 --style squash # Squash merge
tea pr merge 42 --style rebase # Rebase merge
# Close a PR without merging
tea pr close 42
# Reopen a closed PR
tea pr reopen 42
# Clean up branches after PR is merged
tea pr clean 42
```
## Issues
```bash
# List all issues
tea issues ls
# List open issues
tea issues ls --state open
# List issues with specific label
tea issues ls --labels bug
# List issues by author
tea issues ls --author username
# Search issues
tea issues ls --keyword "authentication"
# View specific issue
tea issues 42
# Create an issue
tea issues create \
--title "Bug: Login fails" \
--description "Detailed description of the bug"
# Create issue with labels and milestone
tea issues create -t "Feature request" \
-d "Description" \
--labels enhancement \
--milestone v1.0
# Edit an issue
tea issues edit 42 --title "New title"
# Add labels to an issue
tea issues edit 42 --add-labels bug,urgent
# Remove labels
tea issues edit 42 --remove-labels wontfix
# Assign issue to milestone
tea issues edit 42 --milestone v1.0
# Close an issue
tea issues close 42
# Reopen an issue
tea issues reopen 42
```
## Comments
```bash
# Add comment to issue
tea comment 42 "This is my comment"
# Add comment to PR
tea comment 123 "LGTM! 👍"
# Add multiline comment
tea comment 42 "First line
Second line
Third line"
```
## Releases
```bash
# List all releases
tea releases ls
# Create a release
tea releases create \
--tag v1.0.0 \
--title "Version 1.0.0" \
--note "Release notes here"
# Create release with asset
tea releases create \
--tag v1.0.0 \
-t "v1.0.0" \
-n "Release notes" \
--asset ./binary
# Create release from file
tea releases create \
--tag v1.0.0 \
-t "v1.0.0" \
--note-file RELEASE_NOTES.md
# Create draft release
tea releases create --tag v1.0.0 -t "v1.0.0" --draft
# Create pre-release
tea releases create --tag v1.0.0-beta -t "v1.0.0 Beta" --prerelease
# Edit a release
tea releases edit v1.0.0 --title "New title"
# Delete a release
tea releases delete v1.0.0 --confirm
# Delete release and tag
tea releases delete v1.0.0 --confirm --delete-tag
```
## Labels
```bash
# List all labels
tea labels ls
# Save labels to file
tea labels ls --save > labels.yaml
# Create a label
tea labels create \
--name bug \
--color "#ff0000" \
--description "Bug reports"
# Create labels from file
tea labels create --file labels.yaml
# Update a label
tea labels update \
--id 123 \
--name "critical-bug" \
--color "#cc0000"
# Delete a label
tea labels delete --id 123
```
## Milestones
```bash
# List all milestones
tea milestones ls
# List open milestones
tea milestones ls --state open
# Create a milestone
tea milestones create \
--title "v1.0" \
--description "First stable release"
# Create milestone with deadline
tea milestones create \
-t "v1.0" \
-d "First release" \
--deadline 2026-12-31
# View milestone issues
tea milestones issues v1.0
# Add issue to milestone
tea milestones issues add v1.0 42
# Remove issue from milestone
tea milestones issues remove v1.0 42
# Close a milestone
tea milestones close v1.0
# Reopen a milestone
tea milestones reopen v1.0
# Delete a milestone
tea milestones delete v1.0
```
## Repositories
```bash
# Show current repository details
tea repo
# Clone a repository
tea clone owner/repo
# Clone with depth
tea clone owner/repo --depth 1
# Clone to specific directory
tea clone owner/repo /path/to/dir
```
## Branches
```bash
# List all branches
tea branches ls
# List with details
tea branches ls --output table
```
## Notifications
```bash
# List all notifications
tea notifications
# List only your notifications
tea notifications --mine
# Mark notifications as read
tea notifications --read
```
## Organizations
```bash
# List organizations
tea orgs ls
# Create an organization
tea orgs create --name my-org --description "My organization"
# Delete an organization
tea orgs delete my-org
```
## Open in Browser
```bash
# Open current repo in browser
tea open
# Open specific issue/PR in browser
tea open 42
# Open repo page
tea open --repo owner/repo
```
## Output Formats
```bash
# JSON output
tea pr ls --output json
# YAML output
tea issues ls -o yaml
# CSV output
tea releases ls -o csv
# TSV output
tea milestones ls -o tsv
# Simple output (minimal)
tea pr ls -o simple
```
## Advanced Filtering
```bash
# Filter PRs by multiple criteria
tea pr ls \
--state open \
--labels bug \
--milestone v1.0
# Filter issues by date range
tea issues ls \
--from 2026-01-01 \
--until 2026-12-31
# Complex issue search
tea issues ls \
--author username \
--labels bug,urgent \
--milestone v1.0 \
--state open
# Pagination
tea pr ls --page 2 --limit 50
```
## Using with Specific Repositories
```bash
# Work with a specific repo
tea pr ls --repo owner/repo
# Work with different Gitea login
tea issues ls --login my-gitea
# Override remote
tea pr create --remote origin -t "Title" -d "Description"
```
## Combining with Git
```bash
# Create branch, make changes, create PR
git checkout -b feature/new-thing
# ... make changes ...
git add .
git commit -m "Add new feature"
git push -u origin feature/new-thing
tea pr create -t "Feature: New thing" -d "Description"
# Review PR locally
tea pr checkout 42
# ... test changes ...
git checkout main
tea pr approve 42
tea pr merge 42
```
## Tips and Tricks
```bash
# Get JSON output for scripting
tea pr ls -o json | jq '.[] | select(.state == "open")'
# Check specific fields
tea pr ls --fields index,title,state,author
# Use aliases
alias tpr='tea pr'
alias ti='tea issues'
alias trl='tea releases'
# Quick PR creation from current branch
git push && tea pr create -t "$(git log -1 --pretty=%s)" -d "$(git log -1 --pretty=%b)"
```