refactor(forge): split forge-interaction into specialized GitHub and Gitea skills
Break the monolithic forge-interaction skill into focused, single-responsibility skills for better predictability and maintainability: - Add forge-github skill for GitHub-specific interactions using `gh` CLI - Add forge-gitea skill for Gitea-specific interactions using `tea` CLI - Convert forge-interaction into a router that delegates to specialized skills - Add forge-router skill with model invocation disabled for guidance only - Move all forge-related skills to common/deprecated directory Each specialized skill now contains its own complete decision tree, CLI usage patterns, and authentication checks for its respective forge platform.
This commit is contained in:
@@ -0,0 +1,146 @@
|
||||
---
|
||||
name: forge-gitea
|
||||
---
|
||||
|
||||
# Gitea Forge Interaction
|
||||
|
||||
Use this skill for Gitea forge work when the user wants to interact with Gitea repositories, issues, pull requests, releases, or CI.
|
||||
|
||||
## Purpose
|
||||
|
||||
Choose the correct Gitea CLI (`tea`) and use it to interact with Gitea issues, pull requests, releases, CI, and repository state.
|
||||
|
||||
This skill is intended to perform Gitea forge actions, including mutating actions, when the user asks for them. Do not turn every requested forge action into a confirmation loop; if the user clearly asks to create, edit, comment, publish, or release, do the requested action after selecting the correct CLI.
|
||||
|
||||
## Strict Decision Tree
|
||||
|
||||
Follow this order every time.
|
||||
|
||||
### 1. Determine the target remote
|
||||
|
||||
1. If the user explicitly says which remote or forge to use, use that.
|
||||
2. Else, if user/project memory or repo guidance states where to find the forge, use that.
|
||||
3. Else, if a remote named `forge` exists, use `forge`.
|
||||
4. Else, if the user has configured a default remote, use that.
|
||||
5. Else, use `origin`.
|
||||
|
||||
Useful inspection commands:
|
||||
|
||||
```bash
|
||||
git remote -v
|
||||
git config --get checkout.defaultRemote
|
||||
git config --get clone.defaultRemoteName
|
||||
git config --get branch.$(git branch --show-current).remote
|
||||
```
|
||||
|
||||
Interpretation:
|
||||
|
||||
- A remote named `forge` is the preferred convention for the canonical forge remote.
|
||||
- If no `forge` remote exists, `origin` is the fallback.
|
||||
- If the current branch has an upstream remote and no stronger rule applies, treat that as the user's configured default for the current work.
|
||||
|
||||
Only mention this selection if there is ambiguity or a conflict.
|
||||
|
||||
### 2. Choose the CLI
|
||||
|
||||
Use `tea` for Gitea interactions.
|
||||
|
||||
Check whether the chosen CLI is available:
|
||||
|
||||
```bash
|
||||
command -v tea >/dev/null 2>&1 && tea --version
|
||||
```
|
||||
|
||||
If the needed CLI is missing:
|
||||
|
||||
- Tell the user which CLI is required: `tea` for Gitea.
|
||||
- Tell the user to install it.
|
||||
- If it may already be installed but not discoverable, tell the user to add it to their `PATH`.
|
||||
- Do not use the wrong CLI as a fallback.
|
||||
|
||||
### 3. Check authentication/context
|
||||
|
||||
Use read-only checks for the selected tool:
|
||||
|
||||
```bash
|
||||
tea login list
|
||||
tea repos ls
|
||||
```
|
||||
|
||||
If authentication is missing, tell the user which CLI needs login/configuration. Do not ask the user to paste tokens or secrets.
|
||||
|
||||
### 4. Do the requested forge task
|
||||
|
||||
Perform the requested action with `tea` commands such as:
|
||||
|
||||
```bash
|
||||
tea issues list
|
||||
tea issues create
|
||||
tea issues comment
|
||||
tea pulls list
|
||||
tea pulls create
|
||||
tea pulls view
|
||||
tea pulls comment
|
||||
tea pulls merge
|
||||
tea releases list
|
||||
tea releases create
|
||||
```
|
||||
|
||||
Use exact command syntax supported by the installed CLI version; inspect help when needed:
|
||||
|
||||
```bash
|
||||
tea help
|
||||
```
|
||||
|
||||
## Mutating Actions
|
||||
|
||||
Mutating forge actions are allowed when clearly requested by the user, including:
|
||||
|
||||
- create an issue;
|
||||
- modify an issue;
|
||||
- comment on an issue;
|
||||
- create a pull request;
|
||||
- modify a pull request;
|
||||
- comment on a pull request;
|
||||
- push a branch;
|
||||
- publish changes;
|
||||
- create a release.
|
||||
|
||||
Still be careful with destructive or high-impact actions:
|
||||
|
||||
- Ask before deleting branches, tags, releases, issues, or repositories.
|
||||
- Ask before force-pushing.
|
||||
- Ask before merging a PR unless the user explicitly asked to merge it.
|
||||
- Ask before overwriting existing release assets or tags.
|
||||
|
||||
## Branch and PR Preparation
|
||||
|
||||
Before creating or updating a PR:
|
||||
|
||||
1. Select the remote using the strict decision tree.
|
||||
2. Inspect branch state and upstream tracking.
|
||||
3. Inspect the diff against the target branch.
|
||||
4. Read the PR template if one exists.
|
||||
5. Push the branch if needed and requested by the workflow.
|
||||
6. Create or update the PR.
|
||||
|
||||
Useful local inspection:
|
||||
|
||||
```bash
|
||||
git status --short --branch
|
||||
git branch -vv
|
||||
git diff --stat
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Output Style
|
||||
|
||||
Normally, do not over-explain. If the remote/tool selection is straightforward, just complete the task and summarize the result.
|
||||
|
||||
Report detection details only when there is ambiguity, conflict, missing tooling, or failure. In those cases include:
|
||||
|
||||
- selected remote;
|
||||
- detected forge;
|
||||
- selected CLI;
|
||||
- reason for the choice;
|
||||
- what the user needs to fix, if anything.
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
name: forge-github
|
||||
---
|
||||
|
||||
# GitHub Forge Interaction
|
||||
|
||||
Use this skill for GitHub forge work when the user wants to interact with GitHub repositories, issues, pull requests, releases, or CI.
|
||||
|
||||
## Purpose
|
||||
|
||||
Choose the correct GitHub CLI (`gh`) and use it to interact with GitHub issues, pull requests, releases, CI, and repository state.
|
||||
|
||||
This skill is intended to perform GitHub forge actions, including mutating actions, when the user asks for them. Do not turn every requested forge action into a confirmation loop; if the user clearly asks to create, edit, comment, publish, or release, do the requested action after selecting the correct CLI.
|
||||
|
||||
## Strict Decision Tree
|
||||
|
||||
Follow this order every time.
|
||||
|
||||
### 1. Determine the target remote
|
||||
|
||||
1. If the user explicitly says which remote or forge to use, use that.
|
||||
2. Else, if user/project memory or repo guidance states where to find the forge, use that.
|
||||
3. Else, if a remote named `forge` exists, use `forge`.
|
||||
4. Else, if the user has configured a default remote, use that.
|
||||
5. Else, use `origin`.
|
||||
|
||||
Useful inspection commands:
|
||||
|
||||
```bash
|
||||
git remote -v
|
||||
git config --get checkout.defaultRemote
|
||||
git config --get clone.defaultRemoteName
|
||||
git config --get branch.$(git branch --show-current).remote
|
||||
```
|
||||
|
||||
Interpretation:
|
||||
|
||||
- A remote named `forge` is the preferred convention for the canonical forge remote.
|
||||
- If no `forge` remote exists, `origin` is the fallback.
|
||||
- If the current branch has an upstream remote and no stronger rule applies, treat that as the user's configured default for the current work.
|
||||
|
||||
Only mention this selection if there is ambiguity or a conflict.
|
||||
|
||||
### 2. Choose the CLI
|
||||
|
||||
Use `gh` for GitHub interactions.
|
||||
|
||||
Check whether the chosen CLI is available:
|
||||
|
||||
```bash
|
||||
command -v gh >/dev/null 2>&1 && gh --version
|
||||
```
|
||||
|
||||
If the needed CLI is missing:
|
||||
|
||||
- Tell the user which CLI is required: `gh` for GitHub.
|
||||
- Tell the user to install it.
|
||||
- If it may already be installed but not discoverable, tell the user to add it to their `PATH`.
|
||||
- Do not use the wrong CLI as a fallback.
|
||||
|
||||
### 3. Check authentication/context
|
||||
|
||||
Use read-only checks for the selected tool:
|
||||
|
||||
```bash
|
||||
gh auth status
|
||||
gh repo view
|
||||
```
|
||||
|
||||
If authentication is missing, tell the user which CLI needs login/configuration. Do not ask the user to paste tokens or secrets.
|
||||
|
||||
### 4. Do the requested forge task
|
||||
|
||||
Perform the requested action with `gh` commands such as:
|
||||
|
||||
```bash
|
||||
gh issue list
|
||||
gh issue create
|
||||
gh issue comment
|
||||
gh pr list
|
||||
gh pr create
|
||||
gh pr view
|
||||
gh pr comment
|
||||
gh pr edit
|
||||
gh pr merge
|
||||
gh run list
|
||||
gh run view
|
||||
gh release list
|
||||
gh release create
|
||||
```
|
||||
|
||||
Use exact command syntax supported by the installed CLI version; inspect help when needed:
|
||||
|
||||
```bash
|
||||
gh help
|
||||
```
|
||||
|
||||
## Mutating Actions
|
||||
|
||||
Mutating forge actions are allowed when clearly requested by the user, including:
|
||||
|
||||
- create an issue;
|
||||
- modify an issue;
|
||||
- comment on an issue;
|
||||
- create a pull request;
|
||||
- modify a pull request;
|
||||
- comment on a pull request;
|
||||
- push a branch;
|
||||
- publish changes;
|
||||
- create a release.
|
||||
|
||||
Still be careful with destructive or high-impact actions:
|
||||
|
||||
- Ask before deleting branches, tags, releases, issues, or repositories.
|
||||
- Ask before force-pushing.
|
||||
- Ask before merging a PR unless the user explicitly asked to merge it.
|
||||
- Ask before overwriting existing release assets or tags.
|
||||
|
||||
## Branch and PR Preparation
|
||||
|
||||
Before creating or updating a PR:
|
||||
|
||||
1. Select the remote using the strict decision tree.
|
||||
2. Inspect branch state and upstream tracking.
|
||||
3. Inspect the diff against the target branch.
|
||||
4. Read the PR template if one exists.
|
||||
5. Push the branch if needed and requested by the workflow.
|
||||
6. Create or update the PR.
|
||||
|
||||
Useful local inspection:
|
||||
|
||||
```bash
|
||||
git status --short --branch
|
||||
git branch -vv
|
||||
git diff --stat
|
||||
git diff --check
|
||||
```
|
||||
|
||||
## Output Style
|
||||
|
||||
Normally, do not over-explain. If the remote/tool selection is straightforward, just complete the task and summarize the result.
|
||||
|
||||
Report detection details only when there is ambiguity, conflict, missing tooling, or failure. In those cases include:
|
||||
|
||||
- selected remote;
|
||||
- detected forge;
|
||||
- selected CLI;
|
||||
- reason for the choice;
|
||||
- what the user needs to fix, if anything.
|
||||
+28
-13
@@ -1,26 +1,41 @@
|
||||
---
|
||||
name: forge-interaction
|
||||
description: Use when the user wants forge work such as opening a PR, creating or listing issues, checking CI, looking at the repo, pushing a branch, publishing changes, or making a release on GitHub or Gitea.
|
||||
description: Use when the user wants forge work such as opening a PR, creating or listing issues, checking CI, looking at the repo, pushing a branch, publishing changes, or making a release on GitHub or Gitea. This skill now delegates to specialized skills for better predictability.
|
||||
---
|
||||
|
||||
# Forge Interaction
|
||||
# Forge Interaction (Router)
|
||||
|
||||
Use this skill for Git forge work on GitHub or Gitea, especially when the user asks to:
|
||||
This skill has been refactored into specialized skills for better predictability and maintainability:
|
||||
|
||||
- open a PR;
|
||||
- create, list, modify, or comment on issues;
|
||||
- create, list, modify, comment on, or merge pull requests;
|
||||
- check CI;
|
||||
- look at the repo on the forge;
|
||||
- push a branch;
|
||||
- publish changes;
|
||||
- make or inspect a release.
|
||||
- **GitHub**: Use `/forge-github` for GitHub repositories, issues, pull requests, releases, or CI
|
||||
- **Gitea**: Use `/forge-gitea` for Gitea repositories, issues, pull requests, releases, or CI
|
||||
|
||||
## Purpose
|
||||
|
||||
Choose the correct forge CLI and use it to interact with issues, pull requests, releases, CI, and repository state.
|
||||
This router skill delegates to the appropriate specialized forge interaction skill based on the target forge. Each specialized skill handles one forge type completely, making them more predictable and easier to maintain.
|
||||
|
||||
This skill is intended to perform forge actions, including mutating actions, when the user asks for them. Do not turn every requested forge action into a confirmation loop; if the user clearly asks to create, edit, comment, publish, or release, do the requested action after selecting the correct forge and tool.
|
||||
## When to use:
|
||||
|
||||
- If you're unsure which forge you're working with, use this skill and it will guide you
|
||||
- For general forge work without specifying the forge type
|
||||
- When you want the system to figure out which specialized skill to use
|
||||
|
||||
## Delegation Logic
|
||||
|
||||
The router analyzes your request and determines whether to delegate to:
|
||||
|
||||
1. **GitHub skill** (`/forge-github`) - for GitHub repositories and workflows
|
||||
2. **Gitea skill** (`/forge-gitea`) - for Gitea repositories and workflows
|
||||
|
||||
Each specialized skill contains the complete decision tree and implementation for its respective forge type.
|
||||
|
||||
## Recommendation
|
||||
|
||||
For most predictable results, use the specialized skills directly:
|
||||
- `/forge-github` when working with GitHub
|
||||
- `/forge-gitea` when working with Gitea
|
||||
|
||||
This separation follows the principle of single responsibility and makes each skill more focused and reliable.
|
||||
|
||||
## Strict Decision Tree
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
name: forge-router
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Forge Router
|
||||
|
||||
Choose the right forge interaction skill for your task.
|
||||
|
||||
## When to use:
|
||||
|
||||
- **GitHub**: Use `/forge-github` when working with GitHub repositories, issues, pull requests, releases, or CI.
|
||||
- **Gitea**: Use `/forge-gitea` when working with Gitea repositories, issues, pull requests, releases, or CI.
|
||||
|
||||
## How it works:
|
||||
|
||||
The router delegates to specialized skills that handle each forge type separately. This keeps each skill focused and predictable.
|
||||
|
||||
**GitHub skill** (`/forge-github`):
|
||||
- Handles GitHub-specific interactions using the `gh` CLI
|
||||
- Follows GitHub's API patterns and conventions
|
||||
- Optimized for GitHub's feature set
|
||||
|
||||
**Gitea skill** (`/forge-gitea`):
|
||||
- Handles Gitea-specific interactions using the `tea` CLI
|
||||
- Follows Gitea's API patterns and conventions
|
||||
- Optimized for Gitea's feature set
|
||||
|
||||
## Why separate:
|
||||
|
||||
- **Predictability**: Each skill knows exactly one forge type
|
||||
- **Maintainability**: Changes to GitHub or Gitea logic stay isolated
|
||||
- **Clarity**: Users can see which forge a skill handles at a glance
|
||||
- **Testing**: Each skill can be tested independently
|
||||
|
||||
## Usage examples:
|
||||
|
||||
```
|
||||
# For GitHub work
|
||||
/forge-github create an issue in this repo
|
||||
/forge-github list pull requests
|
||||
/forge-github check CI status
|
||||
|
||||
# For Gitea work
|
||||
/forge-gitea create an issue in this repo
|
||||
/forge-gitea list pull requests
|
||||
/forge-gitea check CI status
|
||||
```
|
||||
|
||||
The router ensures you always use the right tool for the right forge.
|
||||
@@ -0,0 +1,86 @@
|
||||
# Forge Skills
|
||||
|
||||
A collection of specialized forge interaction skills for GitHub and Gitea.
|
||||
|
||||
## Overview
|
||||
|
||||
This directory contains focused skills for interacting with different code hosting platforms:
|
||||
|
||||
- **GitHub**: Use `/forge-github` for GitHub repositories, issues, pull requests, releases, or CI
|
||||
- **Gitea**: Use `/forge-gitea` for Gitea repositories, issues, pull requests, releases, or CI
|
||||
- **Router**: Use `/forge-interaction` to let the system choose the right skill automatically
|
||||
|
||||
## Skill Structure
|
||||
|
||||
Each forge-specific skill is designed with:
|
||||
|
||||
1. **Single Responsibility**: Handles only one forge type (GitHub or Gitea)
|
||||
2. **Predictable Behavior**: Clear decision tree and completion criteria
|
||||
3. **Complete Coverage**: All requested forge actions are supported
|
||||
4. **Error Handling**: Specific guidance for missing tools or authentication
|
||||
|
||||
## Choosing the Right Skill
|
||||
|
||||
### Use `/forge-github` when:
|
||||
- Working with GitHub repositories (`github.com` URLs)
|
||||
- Using the `gh` CLI tool
|
||||
- Interacting with GitHub-specific features (issues, PRs, releases, CI)
|
||||
|
||||
### Use `/forge-gitea` when:
|
||||
- Working with Gitea repositories (`gitea.com` or self-hosted Gitea)
|
||||
- Using the `tea` CLI tool
|
||||
- Interacting with Gitea-specific features (issues, PRs, releases, CI)
|
||||
|
||||
### Use `/forge-interaction` when:
|
||||
- You're unsure which forge you're working with
|
||||
- You want the system to automatically choose the right skill
|
||||
- You prefer a unified interface that handles both platforms
|
||||
|
||||
## Skill Comparison
|
||||
|
||||
| Feature | GitHub Skill | Gitea Skill |
|
||||
|---------|--------------|-------------|
|
||||
| CLI Tool | `gh` | `tea` |
|
||||
| Platform | GitHub | Gitea |
|
||||
| Focus | GitHub-specific | Gitea-specific |
|
||||
| Predictability | High | High |
|
||||
| Maintenance | Isolated | Isolated |
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```
|
||||
# For GitHub work
|
||||
/forge-github create an issue in this repo
|
||||
/forge-github list pull requests
|
||||
/forge-github check CI status
|
||||
/forge-github publish a new release
|
||||
|
||||
# For Gitea work
|
||||
/forge-gitea create an issue in this repo
|
||||
/forge-gitea list pull requests
|
||||
/forge-gitea check CI status
|
||||
/forge-gitea publish a new release
|
||||
|
||||
# Let the system decide
|
||||
/forge-interaction create a PR for this feature
|
||||
```
|
||||
|
||||
## Why Separate Skills?
|
||||
|
||||
1. **Predictability**: Each skill knows exactly one forge type
|
||||
2. **Maintainability**: Changes to GitHub or Gitea logic stay isolated
|
||||
3. **Clarity**: Users can see which forge a skill handles at a glance
|
||||
4. **Testing**: Each skill can be tested independently
|
||||
5. **Cognitive Load**: Users remember fewer skills and their specific purposes
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `/forge-router` - High-level guidance for choosing the right forge skill
|
||||
- `/forge-preferences` - Personal or project-specific forge configurations
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Choose the appropriate skill based on your forge platform
|
||||
2. Ensure the required CLI tool (`gh` or `tea`) is installed
|
||||
3. Configure authentication for your forge platform
|
||||
4. Start with simple actions and build up to more complex workflows
|
||||
Reference in New Issue
Block a user