tea-skills: A Skill Set for Gitea/Forgejo Agents Based on tea CLI

tea-skills is a skill set that provides AI Agents with operational capabilities for the Gitea/Forgejo code hosting platform. By encapsulating the tea CLI, it enables automated management of core workflows such as Issues, PRs, milestones, and labels. It solves the problem of seamless collaboration between AI Agents and self-hosted code platforms, allowing Agents to directly participate in software development processes. It is suitable for organizations and individual developers who need independent control over their code.

Gitea and Forgejo

Gitea is a lightweight self-hosted Git service with low resource consumption and simple deployment. Forgejo is a community-driven fork of Gitea that adds enterprise-grade features. Both provide GitHub-like functionalities such as Git repository hosting, Issue tracking, and PR review, making them excellent alternatives to GitHub.

tea CLI

tea is the official command-line tool for Gitea, supporting terminal operations like repository management, Issue/PR handling, label/milestone management, etc. It allows interaction with Gitea/Forgejo instances without a browser.

Agent-Native Design

• Structured Output: Ensure all outputs are in JSON/YAML format for easy parsing by Agents
• Error Recovery: Provide clear error messages and recovery suggestions
• Idempotency: Key operations support safe retries

Modular Skill Architecture

Skill Module	Function Scope
issue	Issue creation, query, update, comment, label management
pr	PR creation, review, merge, conflict resolution
milestone	Milestone creation, progress tracking, status management
label	Label creation, application, system management
repo	Repository query, branch management

Issue Workflow Automation

• Intelligent Creation: Generate Issues based on context, automatically extract titles/descriptions/labels
• Bulk Query: Filter Issues from multiple dimensions and export structured data
• Automatic Labeling: Suggest or apply labels based on content
• Comment Synchronization: Add comments, update status, and sync with external systems

PR Collaboration

• Creation Assistance: Fill description templates and link to Issues
• Change Summary: Analyze diffs to generate key modification notes
• Review Tracking: Monitor status, remind reviewers, and auto-merge
• Conflict Assistance: Analyze conflict causes and provide resolution suggestions

Milestone Management

• Planning: Create milestones, set deadlines, link to Issues/PRs
• Progress Tracking: Monitor completion rate and identify blocking items
• Report Generation: Automatically generate progress reports

Scenario 1: Automated Bug Report Handling

When a user reports a bug, the Agent can analyze the description to extract information, automatically create a formatted Issue, apply labels, link to similar Issues, and return the link.

Scenario 2: PR Review Assistant

When a new PR is submitted, the Agent analyzes the diff to check compliance, generates review comments or LGTM, and auto-merges and updates the Issue status if conditions are met.

Scenario 3: Release Management

When preparing for a release, the Agent checks the milestone completion status, identifies blocking PRs, generates release notes, creates tags, and closes the milestone.

tea CLI Encapsulation Layer

Instead of directly calling APIs, it uses tea CLI encapsulation:

• Authentication Reuse: Inherit tea configuration and authentication information
• Command Reuse: Use mature tea commands to reduce development effort
• Output Standardization: Rely on tea's JSON output interface

Configuration Management

• Environment Variables: Configure instance address and authentication
• Configuration Files: Compatible with existing tea user environments
• Runtime Configuration: Dynamically switch target instances

Error Handling

• Classified Error Codes: Distinguish between retryable, authentication, and permission errors
• Exponential Backoff: Auto-retry for retryable errors
• Detailed Logs: Record operation logs for easy debugging

Applicable Scenarios

• Self-hosted Git service users: Directly operate Gitea/Forgejo
• Privacy-sensitive projects: Achieve automation with private instances
• CI/CD integration: Act as a bridge between Agents and code platforms
• Enterprise internal tools: Build basic components for DevOps Agents

Tool Comparison

Feature	GitHub CLI (gh)	tea CLI	tea-skills
Target Platform	GitHub	Gitea/Forgejo	Gitea/Forgejo
User Type	Human Developers	Human Developers	AI Agent
Output Format	Human-readable	Human/machine-readable	Machine-first
Agent Integration	Requires adaptation	Requires adaptation	Native support
Error Recovery	Manual	Manual	Automatic

Future Development

• Extend support to GitLab, Bitbucket, and other platforms
• Integrate code analysis tools to provide intelligent review suggestions
• Support workflow orchestration across repositories/milestones
• Integrate with visualization tools

Conclusion

tea-skills fills the gap in integration between AI Agents and self-hosted code platforms. It is an important tool for Gitea/Forgejo users to enable AI participation in development processes, and will play an even greater role as AI is applied more widely in development.