Add merging documentation to review-pr command

- Document tea pulls merge as the correct merge method
- Add warning against using Gitea API with admin credentials
- Document tea comment as alternative to interactive tea pulls review

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

agents/code-reviewer/AGENT.md

@@ -13,7 +13,7 @@ You are a code review specialist that provides immediate, structured feedback on
 
 You will receive a PR number to review. Follow this process:
 
-1. Fetch PR diff using `tea pulls <number> -f diff`
+1. Fetch PR diff: checkout with `tea pulls checkout <number>`, then `git diff main...HEAD`
 2. Analyze the diff for issues in these categories:
    - **Code Quality**: Readability, maintainability, complexity
    - **Bugs**: Logic errors, edge cases, null checks
@@ -22,7 +22,7 @@ You will receive a PR number to review. Follow this process:
    - **Test Coverage**: Missing tests, untested edge cases
 3. Generate a structured review comment
 4. Post the review using `tea comment <number> "<review body>"`
-5. **If verdict is LGTM**: Approve with `tea pulls approve <number>`, then auto-merge with `tea pulls merge <number> --style rebase`
+5. **If verdict is LGTM**: Merge with `tea pulls merge <number> --style rebase`
 6. **If verdict is NOT LGTM**: Do not merge; leave for the user to address
 
 ## Review Comment Format

agents/product-manager/AGENT.md

@@ -23,4 +23,3 @@ You can:
 - Always fetch current issue state before making changes
 - Ask for approval before creating or modifying issues
 - Provide clear summaries of actions taken
-- Use the gitea skill for all issue/PR operations

commands/create-issue.md

@@ -5,7 +5,7 @@ argument-hint: [title] or "batch"
 
 # Create Issue(s)
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 ## Single Issue (default)
 If title provided, create an issue with that title and ask for description.

commands/dashboard.md

@@ -4,7 +4,7 @@ description: Show dashboard of open issues, PRs awaiting review, and CI status.
 
 # Repository Dashboard
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 Fetch and display:
 1. All open issues

commands/groom.md

@@ -5,7 +5,9 @@ argument-hint: [issue-number]
 
 # Groom Issues
 
-Use the gitea, backlog-grooming, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 ## If issue number provided ($1):
 

commands/plan-issues.md

@@ -5,7 +5,9 @@ argument-hint: <feature-description>
 
 # Plan Feature: $1
 
-Use the gitea, roadmap-planning, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/roadmap-planning/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 1. **Understand the feature**: Analyze what "$1" involves
 2. **Explore the codebase** if needed to understand context

commands/review-pr.md

@@ -5,7 +5,7 @@ argument-hint: <pr-number>
 
 # Review PR #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View PR details** including description and metadata
 2. **Get the diff** to review the changes
@@ -20,3 +20,19 @@ Ask the user what action to take:
 - **Merge**: Post review summary as comment, then merge with rebase style
 - **Request changes**: Leave feedback without merging
 - **Comment only**: Add a comment for discussion
+
+## Merging
+
+Always use tea CLI for merges to preserve user attribution:
+
+```bash
+tea pulls merge <number> --style rebase
+```
+
+For review comments, use `tea comment` since `tea pulls review` is interactive-only:
+
+```bash
+tea comment <number> "<review summary>"
+```
+
+> **Warning**: Never use the Gitea API with admin credentials for user-facing operations like merging. This causes the merge to be attributed to the admin account instead of the user.

commands/roadmap.md

@@ -4,7 +4,7 @@ description: View current issues as a roadmap. Shows open issues organized by st
 
 # Roadmap View
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **Fetch all open issues**
 2. **Analyze dependencies** from issue descriptions

commands/work-issue.md

@@ -5,7 +5,7 @@ argument-hint: <issue-number>
 
 # Work on Issue #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View the issue** to understand requirements
 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`

docs/writing-commands.md

@@ -72,7 +72,7 @@ argument-hint: <issue-number>
 
 # Work on Issue #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View the issue** to understand requirements
 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
@@ -138,7 +138,7 @@ argument-hint: [issue-number]
 
 # Groom Issues
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 ## If issue number provided ($1):
 1. **Fetch the issue** details
@@ -163,7 +163,7 @@ argument-hint: [title] or "batch"
 
 # Create Issue(s)
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 ## Single Issue (default)
 If title provided, create an issue with that title.
@@ -176,41 +176,45 @@ If $1 is "batch":
 4. Create each issue
 ```
 
-## Invoking Skills
+## Including Skills
 
-Commands reference skills by name to gain domain knowledge. When a skill is referenced, Claude reads the skill file before proceeding.
+Commands include skills using the `@` file reference syntax. This automatically injects the skill content into the command context when the command is invoked.
 
-### Explicit Reference
+### File Reference Syntax
+
+Use the `@` prefix followed by the path to the skill file:
 
 ```markdown
 # Groom Issues
 
-Use the **gitea**, **backlog-grooming**, and **issue-writing** skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 1. **Fetch the issue** details
 2. **Evaluate** against grooming checklist
 ...
 ```
 
-The phrase "Use the gitea, backlog-grooming and issue-writing skills" tells Claude to read and apply knowledge from those skill files.
+When the command runs, the content of each referenced skill file is automatically loaded into context.
 
-### Skill-Based Approach
+### Why File References?
 
-Commands should reference skills rather than embedding CLI commands directly:
+**DO NOT** use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the skill content is available.
 
-```markdown
+| Pattern | Behavior |
-1. **Fetch the issue** details
+|---------|----------|
-```
+| `@~/.claude/skills/gitea/SKILL.md` | Content automatically injected |
+| "Use the gitea skill" | Relies on auto-activation (~20% success) |
 
-This relies on the `gitea` skill to provide the CLI knowledge.
+### When to Include Skills
 
-### When to Reference Skills
+| Include explicitly | Skip skill reference |
-
+|-------------------|---------------------|
-| Reference explicitly | Reference implicitly |
+| CLI syntax is needed | Well-known commands |
-|---------------------|---------------------|
+| Core methodology required | Simple operations |
-| Core methodology is needed | Just using a tool |
+| Quality standards matter | One-off actions |
-| Quality standards matter | Simple operations |
+| Patterns should be followed | No domain knowledge needed |
-| Patterns should be followed | Well-known commands |
 
 ## Invoking Agents
 
@@ -313,7 +317,7 @@ argument-hint: <issue-number>
 
 # Work on Issue #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View the issue** to understand requirements
 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
@@ -340,7 +344,7 @@ description: Show dashboard of open issues, PRs awaiting review, and CI status.
 
 # Repository Dashboard
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 Fetch and display:
 1. All open issues
@@ -365,7 +369,9 @@ argument-hint: [issue-number]
 
 # Groom Issues
 
-Use the gitea, backlog-grooming, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 ## If issue number provided ($1):
 1. **Fetch the issue** details
@@ -388,7 +394,7 @@ Use the gitea, backlog-grooming, and issue-writing skills.
 **Key patterns:**
 - **Optional argument**: `[issue-number]` with brackets
 - **Mode switching**: Different behavior based on argument presence
-- **Explicit skill reference**: "Use the gitea, backlog-grooming and issue-writing skills"
+- **Skill file references**: Uses `@~/.claude/skills/` to include multiple skills
 - **Approval workflow**: "Ask user if they want to apply changes"
 - **Categorization**: Groups items for presentation
 
@@ -402,7 +408,9 @@ argument-hint: <feature-description>
 
 # Plan Feature: $1
 
-Use the gitea, roadmap-planning, and issue-writing skills.
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/roadmap-planning/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
 
 1. **Understand the feature**: Analyze what "$1" involves
 2. **Explore the codebase** if needed to understand context
@@ -422,7 +430,7 @@ Use the gitea, roadmap-planning, and issue-writing skills.
 ```
 
 **Key patterns:**
-- **Multi-skill composition**: References three skills together
+- **Multi-skill composition**: Includes three skills via `@~/.claude/skills/`
 - **Codebase exploration**: May need to understand context
 - **Structured output**: Template for presenting the plan
 - **Two-phase execution**: Plan first, then execute after approval
@@ -438,7 +446,7 @@ argument-hint: <pr-number>
 
 # Review PR #$1
 
-Use the gitea skill.
+@~/.claude/skills/gitea/SKILL.md
 
 1. **View PR details** including description and metadata
 2. **Get the diff** to review the changes
@@ -641,7 +649,7 @@ Update references:
 - [ ] Frontmatter includes argument-hint (if arguments needed)
 - [ ] Workflow steps are clear and numbered
 - [ ] Commands and tools are specified explicitly
-- [ ] Skills are referenced where methodology matters
+- [ ] Skills are included via `@~/.claude/skills/<name>/SKILL.md` file references
 - [ ] Approval points exist before significant actions
 - [ ] Edge cases are handled (no data, invalid input)
 - [ ] Output formatting is specified

docs/writing-skills.md

@@ -2,11 +2,77 @@
 
 A guide to creating reusable knowledge modules for the Claude Code AI workflow system.
 
+> **Official Documentation**: For the most up-to-date information, see https://code.claude.com/docs/en/skills
+
 ## What is a Skill?
 
-Skills are **knowledge modules**—focused documents that teach Claude how to do something well. Unlike commands (which define workflows) or agents (which execute tasks), skills are passive: they encode domain expertise, patterns, and best practices that can be referenced when needed.
+Skills are **model-invoked knowledge modules**—Claude automatically applies them when your request matches their description. Unlike commands (which require explicit `/command` invocation), skills are triggered automatically based on semantic matching.
 
-Think of skills as the "how-to guides" that inform Claude's work. A skill doesn't act on its own—it provides the knowledge that commands and agents use to complete their tasks effectively.
+## YAML Frontmatter (Required)
+
+Every `SKILL.md` file **must** start with YAML frontmatter. This is how Claude discovers and triggers skills.
+
+### Format Requirements
+
+- Must start with `---` on **line 1** (no blank lines before it)
+- Must end with `---` before the markdown content
+- Use spaces for indentation (not tabs)
+
+### Required Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | **Yes** | Lowercase letters, numbers, and hyphens only (max 64 chars). Should match directory name. |
+| `description` | **Yes** | What the skill does and when to use it (max 1024 chars). **This is critical for triggering.** |
+
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. |
+| `model` | Specific model to use when skill is active (e.g., `claude-sonnet-4-20250514`). |
+
+### Writing Effective Descriptions
+
+The `description` field determines when Claude applies the skill. A good description answers:
+
+1. **What does this skill do?** List specific capabilities.
+2. **When should Claude use it?** Include trigger terms users would mention.
+
+**Bad (too vague):**
+```yaml
+description: Helps with documents
+```
+
+**Good (specific with trigger terms):**
+```yaml
+description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
+```
+
+### Example Frontmatter
+
+```yaml
+---
+name: gitea
+description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, or when the user mentions tea, gitea, or issue numbers.
+---
+
+# Gitea CLI (tea)
+
+[Rest of skill content...]
+```
+
+## Subagents and Skills
+
+Subagents **do not automatically inherit skills** from the main conversation. To give a subagent access to skills, list them in the agent's `skills` field:
+
+```yaml
+---
+name: code-reviewer
+description: Review code for quality and best practices
+skills: gitea, code-review
+---
+```
 
 ## File Structure
 
@@ -77,39 +143,29 @@ Quick-reference tables, checklists, or commands.
 
 Not every skill needs all sections—include what's relevant. Some skills are primarily patterns (like `issue-writing`), others are reference-heavy (like `gitea`).
 
-## How Skills are Loaded
+## How Skills are Discovered and Triggered
 
-Skills are loaded by **explicit reference**. When a command or agent mentions a skill by name, Claude reads the skill file to gain that knowledge.
+Skills are **model-invoked**: Claude decides which skills to use based on your request.
 
-### Referenced by Commands
+### Discovery Process
 
-Commands reference skills in their instructions:
+1. **At startup**: Claude loads only the `name` and `description` of each available skill
+2. **On request**: Claude matches your request against skill descriptions using semantic similarity
+3. **Activation**: When a match is found, Claude asks to use the skill before loading the full content
 
-```markdown
+### Subagent Access
-# Groom Issues
 
-Use the **backlog-grooming** and **issue-writing** skills to review and improve issues.
+Subagents (defined in `.claude/agents/`) must explicitly list which skills they can use:
 
-1. Fetch open issues...
+```yaml
+---
+name: product-manager
+description: Manages backlog and roadmap
+skills: gitea, issue-writing, backlog-grooming, roadmap-planning
+---
 ```
 
-When this command runs, Claude reads both referenced skills before proceeding.
+**Important**: Built-in agents and the Task tool do not have access to skills. Only custom subagents with an explicit `skills` field can use them.
-
-### Referenced by Agents
-
-Agents list their skills explicitly:
-
-```markdown
-# Product Manager Agent
-
-## Skills
-- gitea
-- issue-writing
-- backlog-grooming
-- roadmap-planning
-```
-
-When spawned, the agent has access to all listed skills as part of its context.
 
 ### Skills Can Reference Other Skills
 
@@ -430,14 +486,26 @@ Keep skills current:
 
 ## Checklist: Before Submitting a New Skill
 
+### Frontmatter (Critical)
+- [ ] YAML frontmatter starts on line 1 (no blank lines before `---`)
+- [ ] `name` field uses lowercase letters, numbers, and hyphens only
+- [ ] `name` matches the directory name
+- [ ] `description` lists specific capabilities
+- [ ] `description` includes "Use when..." with trigger terms
+
+### File Structure
 - [ ] File is at `skills/<name>/SKILL.md`
 - [ ] Name follows kebab-case convention
+
+### Content Quality
 - [ ] Skill focuses on a single domain
 - [ ] Guidelines are specific and actionable
 - [ ] Examples illustrate each major point
 - [ ] Templates are provided where appropriate
 - [ ] Common mistakes are documented
-- [ ] Skill is referenced by at least one command or agent
+
+### Integration
+- [ ] Skill is listed in relevant subagent `skills` fields if needed
 
 ## See Also
 

settings.json

@@ -1,5 +1,15 @@
 {
   "model": "opus",
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(mkdir:*)",
+      "Bash(find:*)",
+      "Bash(curl:*)",
+      "Bash(tea:*)",
+      "WebSearch"
+    ]
+  },
   "statusLine": {
     "type": "command",
     "command": "input=$(cat); current_dir=$(echo \"$input\" | jq -r '.workspace.current_dir'); model=$(echo \"$input\" | jq -r '.model.display_name'); style=$(echo \"$input\" | jq -r '.output_style.name'); git_info=\"\"; if [ -d \"$current_dir/.git\" ]; then cd \"$current_dir\" && branch=$(git branch --show-current 2>/dev/null) && status=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') && git_info=\" [$branch$([ \"$status\" != \"0\" ] && echo \"*\")]\"; fi; printf \"\\033[2m$(whoami)@$(hostname -s) $(basename \"$current_dir\")$git_info | $model ($style)\\033[0m\""

skills/backlog-grooming/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: backlog-grooming
+description: Review and improve existing issues for clarity and actionability. Use when grooming the backlog, reviewing issue quality, cleaning up stale issues, or when the user wants to improve existing issues.
+---
+
 # Backlog Grooming
 
 How to review and improve existing issues.

skills/code-review/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: code-review
+description: Review code for quality, bugs, security, and style issues. Use when reviewing pull requests, checking code quality, looking for bugs or security vulnerabilities, or when the user asks for a code review.
+---
+
 # Code Review
 
 Guidelines for reviewing code changes in pull requests.

skills/gitea/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: gitea
+description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
+---
+
 # Gitea CLI (tea)
 
 Command-line interface for interacting with Gitea repositories.
@@ -78,7 +83,10 @@ tea pulls --state closed             # Closed/merged PRs
 # View PR
 tea pulls <number>                   # PR details
 tea pulls <number> --comments        # Include comments
-tea pulls <number> -f diff           # PR diff
+
+# View PR diff (tea doesn't have a diff command, use git)
+tea pulls checkout <number>          # First checkout the PR branch
+git diff main...HEAD                 # Diff against main branch
 
 # Create PR
 tea pulls create --title "<title>" --description "<body>"
@@ -119,15 +127,15 @@ tea clone <owner>/<repo>             # Clone repository
 tea comment <number> "<comment body>"
 tea comment 3 "LGTM, ready to merge"
 
-# Multiline comments (use heredoc)
+# Multiline comments (use quoted strings with literal newlines)
-tea comment 3 "$(cat <<'EOF'
+tea comment 3 "## Review Summary
-## Review Summary
+
 - Code looks good
-- Tests pass
+- Tests pass"
-EOF
-)"
 ```
 
+> **Warning**: Do not use heredoc syntax `$(cat <<'EOF'...EOF)` with `tea comment` - it causes the command to be backgrounded and fail silently.
+
 ### Notifications
 
 ```bash
@@ -155,6 +163,7 @@ tea issues -r owner/repo             # Specify repo directly
 ## Tips
 
 - **View single issue**: Use `tea issues <number>` (NOT `tea issues view <number>` - there is no `view` subcommand)
+- **PR description flag**: Use `--description` or `-d` (NOT `--body` like gh CLI)
 - Always verify you're in the correct repository before running commands
 - Use `tea issues` to find issue numbers before viewing/editing
 - Reference issues in PR bodies with `Closes #N` for auto-linking

skills/issue-writing/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: issue-writing
+description: Write clear, actionable issues with proper structure and acceptance criteria. Use when creating issues, writing bug reports, feature requests, or when the user needs help structuring an issue.
+---
+
 # Issue Writing
 
 How to write clear, actionable issues.

skills/roadmap-planning/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: roadmap-planning
+description: Plan features and break down work into implementable issues. Use when planning a feature, creating a roadmap, breaking down large tasks, or when the user needs help organizing work into issues.
+---
+
 # Roadmap Planning
 
 How to plan features and create issues for implementation.