diff --git a/CLAUDE.md b/CLAUDE.md
index 96e8ebb..4fa3dae 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,14 @@ The `tea` command-line tool is Gitea's official CLI for interacting with Gitea i
 
 ### Context Detection
 
-Tea automatically detects repository context from the current working directory. It reads `.git/config` to determine the Gitea remote and repository.
+**CRITICAL**: Tea REQUIRES being run from within a git repository directory that has a Gitea remote configured. It reads `.git/config` to determine the Gitea remote and repository.
+
+**Before running ANY tea command, you MUST:**
+1. Navigate to a repository directory: `cd /path/to/repo`
+2. Verify a Gitea remote exists: `git remote -v` (should show git.ajet.fyi or similar)
+3. Confirm you're authenticated: `tea whoami`
+
+Most tea commands will FAIL if these requirements aren't met. The `--repo owner/repo` flag exists but is unreliable for many operations.
 
 ### Authentication
 
@@ -64,27 +71,38 @@ tea releases create --tag v1.0.0 -t "v1.0.0" -n "Release notes"
 
 ## Important Notes for Claude Code
 
-### Always Check Authentication First
+### Critical Pre-requisites (CHECK THESE FIRST!)
 
-Before running `tea` commands, verify the user is logged in:
+**BEFORE suggesting or running ANY `tea` command, you MUST verify:**
 
+1. **Repository Context**: User is in a git repository directory with a Gitea remote
+   ```bash
+   pwd                # Verify current directory
+   ls .git            # Confirm it's a git repo
+   git remote -v      # Must show a Gitea remote (git.ajet.fyi, etc.)
+   ```
+
+2. **Authentication**: User is logged in to tea
+   ```bash
+   tea whoami
+   ```
+
+**If not in a repository:** Guide the user to navigate to their repository first:
 ```bash
-tea whoami
+cd /path/to/repo
 ```
 
-If not authenticated, guide the user to run:
+**If no Gitea remote exists:** Tea will not work. User must add a Gitea remote:
+```bash
+git remote add origin https://git.ajet.fyi/owner/repo.git
+```
 
+**If not authenticated:** Guide the user to login:
 ```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
+**IMPORTANT**: The `--repo owner/repo` flag is unreliable and should NOT be used as a workaround. Always ensure proper repository context first.
 
 ### Output Formats
 
@@ -209,11 +227,12 @@ When adding new examples or workflows:
 
 ## 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
+- **Not in repo directory**: This is the #1 cause of tea command failures. Tea REQUIRES being in a git repository directory with a Gitea remote. Always verify with `pwd`, `ls .git`, and `git remote -v` before running tea commands.
+- **Missing Gitea remote**: Tea only works with Gitea remotes (e.g., git.ajet.fyi). It will NOT work with GitHub, GitLab, or other Git hosting services.
+- **Using `--repo` flag as workaround**: The `--repo owner/repo` flag is unreliable. Don't use it as a substitute for proper repository context.
+- **Missing authentication**: Always check `tea whoami` before running commands
+- **Insufficient token permissions**: Token needs appropriate scopes for the operations you're performing
+- **Branch not pushed**: Can't create PR for unpushed branches - ensure `git push` succeeds first
 
 ## Testing
 
diff --git a/README.md b/README.md
index 1638bea..43efabd 100644
--- a/README.md
+++ b/README.md
@@ -63,13 +63,16 @@ 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:
+The skill is located in the `skills/tea/` directory. To use it with Claude Code, symlink it to your Claude Code skills directory:
 
-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
-   ```
+```bash
+ln -s /path/to/gong-fu-cha/skills/tea ~/.claude/skills/tea
+```
+
+For example:
+```bash
+ln -s ~/repos/ajet-industries/gong-fu-cha/skills/tea ~/.claude/skills/tea
+```
 
 ### Using the Skill
 
@@ -130,16 +133,19 @@ tea releases create --tag v1.0.0 -t "Version 1.0.0" -n "Release notes"
 
 - **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
+- **Skill Documentation**: See `skills/tea/SKILL.md` for Claude Code integration details
+- **Examples**: See `skills/tea/examples.md` for usage examples
 
 ## Repository Structure
 
 ```
 gong-fu-cha/
 ├── skills/
-│   └── SKILL.md         # Claude Code skill definition
-├── README.md            # This file
-└── CLAUDE.md            # Instructions for Claude Code
+│   └── tea/
+│       ├── SKILL.md      # Claude Code skill definition
+│       └── examples.md   # Usage examples
+├── README.md             # This file
+└── CLAUDE.md             # Instructions for Claude Code
 ```
 
 ## Why "Gong Fu Cha"?
diff --git a/skills/SKILL.md b/skills/tea/SKILL.md
similarity index 65%
rename from skills/SKILL.md
rename to skills/tea/SKILL.md
index 14e961a..5e30036 100644
--- a/skills/SKILL.md
+++ b/skills/tea/SKILL.md
@@ -20,6 +20,16 @@ Use this skill when you need to:
 
 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.
 
+## ⚠️ Critical Requirements
+
+**BEFORE running any `tea` commands, you MUST:**
+
+1. **Be inside a git repository directory** - Navigate to a repository with `cd /path/to/repo`
+2. **Have a Gitea remote configured** - The repository must have a remote pointing to your Gitea instance (e.g., git.ajet.fyi)
+3. **Be authenticated** - Run `tea whoami` to verify you're logged in
+
+Most `tea` commands will FAIL if you're not in a repository directory with a Gitea remote. The `--repo` flag exists but is unreliable for many operations.
+
 ## Setup
 
 ### Check if logged in
@@ -218,13 +228,21 @@ tea open 42  # Open issue/PR #42
 
 ### Repository Context
 
-Tea automatically detects the repository from your current directory. Override with:
+**REQUIREMENT**: Tea requires you to be in a git repository directory with a Gitea remote configured. It reads `.git/config` to determine the repository context.
 
+**Verify your repository has a Gitea remote:**
 ```bash
-tea pr ls --repo owner/repo
-tea issues create --repo owner/repo -t "Title"
+git remote -v
+# Should show a remote pointing to your Gitea instance (e.g., git.ajet.fyi)
 ```
 
+**If no Gitea remote exists, add one:**
+```bash
+git remote add origin https://git.ajet.fyi/owner/repo.git
+```
+
+**The `--repo` flag is unreliable** - While tea provides a `--repo owner/repo` flag, many commands don't work correctly with it. Always run tea from within the repository directory.
+
 ### Login Selection
 
 Use a specific Gitea login:
@@ -282,37 +300,60 @@ 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
+- **Repository context REQUIRED**: You MUST run tea from within a git repository directory that has a Gitea remote configured. Commands will fail otherwise.
+- **Verify before running**: Always check `git remote -v` to ensure you have a Gitea remote before running tea commands
+- **Navigate to repo first**: Use `cd /path/to/repo` to change to your repository directory before running tea
+- **Multiple logins**: You can configure multiple Gitea instances with `tea login add`
 - **Default login**: Set a default login with `tea login default`
-- **Token permissions**: Ensure your access token has appropriate scopes
+- **Token permissions**: Ensure your access token has appropriate scopes for the operations you need
 - **Help available**: Run `tea <command> --help` for detailed options
 - **Manual pages**: Use `tea man` for comprehensive documentation
 
 ## Typical Workflows
 
+### Pre-flight Checklist
+
+**BEFORE running any tea workflow, verify:**
+
+```bash
+# 1. Check you're in a git repository
+pwd  # Should show your repo directory
+ls .git  # Should exist
+
+# 2. Verify Gitea remote is configured
+git remote -v  # Should show git.ajet.fyi or your Gitea instance
+
+# 3. Check authentication
+tea whoami  # Should show your username
+```
+
+If any of these fail, fix them before proceeding with tea commands.
+
 ### Creating a PR from a feature branch
 
-1. Make changes and commit
-2. Push to remote
-3. Create PR:
+1. **Verify you're in the correct repository directory**
+2. Make changes and commit
+3. Push to remote
+4. Create PR:
    ```bash
    tea pr create -t "Feature: New capability" -d "Description of changes"
    ```
-4. Wait for review or review yourself
+5. 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`
+1. **Navigate to repository directory**: `cd /path/to/repo`
+2. List PRs: `tea pr ls`
+3. Checkout locally: `tea pr checkout 42`
+4. Test the changes
+5. Approve: `tea pr approve 42`
+6. Merge: `tea pr merge 42 --style squash`
 
 ### Creating a release
 
-1. Ensure you're on the right branch/commit
-2. Create release:
+1. **Navigate to repository directory**: `cd /path/to/repo`
+2. Ensure you're on the right branch/commit
+3. Create release:
    ```bash
    tea releases create --tag v1.0.0 --title "Version 1.0.0" \
      --note "Release notes" --asset ./binary
@@ -320,10 +361,11 @@ tea pr ls --limit 50
 
 ### 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`
+1. **Navigate to repository directory**: `cd /path/to/repo`
+2. List open issues: `tea issues ls --state open`
+3. View specific issue: `tea issues 42`
+4. Add comment: `tea comment 42 "Working on this"`
+5. Close when done: `tea issues close 42`
 
 ## Getting Help
 
diff --git a/skills/examples.md b/skills/tea/examples.md
similarity index 100%
rename from skills/examples.md
rename to skills/tea/examples.md