docs: fix command documentation accuracy and add --agent flag docs

Author: yeasy

.agent/rules/coding.md

@@ -0,0 +1,58 @@
+---
+trigger: always_on
+---
+
+# Project Rules & Engineering Standards
+
+This document establishes the non-negotiable engineering standards for this project. These rules are designed to maintain codebase health, ensure velocity, and prevent technical debt accumulation.
+
+**All contributors (human and AI) must adhere to these guidelines.**
+
+---
+
+## 1. The Golden Rule: Green Build Policy
+> *The main branch must always be in a deployable state.*
+
+* **Passing Tests**: No code may be merged unless **100%** of the project's automated tests (Unit, Integration, E2E) pass.
+* **No Broken Windows**: If a build fails, fixing it is the highest priority. No new features can be merged until the build is green.
+* **Local Verification**: Before pushing/submitting a PR, you must run the test suite locally. "It works on my machine" is not a valid excuse for CI failures.
+
+## 2. Testing Protocols
+> *If it's not tested, it's broken.*
+
+* **Regression Tests**: Every bug fix **MUST** be accompanied by a new test case that reproduces the bug and verifies the fix.
+* **New Features**: All new functionality requires corresponding unit tests.
+* **Test Quality**:
+    * Tests must be deterministic (no flaky tests).
+    * Tests must be readable and test behavior, not implementation details.
+
+## 3. Documentation Hygiene
+> *Code is the truth, but documentation is the map.*
+
+* **Atomic Updates**: Documentation updates (README, API docs, inline comments) **MUST** be included in the same Pull Request/Commit as the code change.
+    * *Example*: If you add a new flag or environment variable, update the configuration guide immediately.
+* **Why, Not What**: Comments should explain *why* a decision was made or *why* the logic is complex. Do not write comments that simply repeat what the code does.
+* **Obsolescence**: Stale documentation is worse than no documentation. Delete docs that no longer reflect the codebase.
+
+## 4. Code Review & Workflow
+* **Small, Atomic Commits**:
+    * A Change List (CL) or Pull Request (PR) should focus on **one** thing.
+    * Avoid mixing formatting changes, refactoring, and feature work in the same commit.
+* **Conventional Commits**:
+    * Use semantic commit messages: `feat: ...`, `fix: ...`, `docs: ...`, `refactor: ...`.
+* **Linting & Formatting**:
+    * Code must be formatted automatically (e.g., Prettier, gofmt, Black).
+    * Zero linting warnings allowed in the final merge.
+
+## 5. Dependency Management
+* **Explicit Versions**: All dependencies must be pinned to specific versions (via `package-lock.json`, `go.sum`, `requirements.txt`, etc.).
+* **Minimalism**: Do not introduce a heavy library for a trivial utility function that can be written in 5 lines of code.
+
+## 6. AI & Copilot Usage
+* **Verification**: Code generated by AI (Cursor, Copilot, ChatGPT) must be reviewed line-by-line.
+* **No Hallucinations**: Verify that imported libraries actually exist and APIs are correct.
+* **Context**: AI-generated code must match the existing style and patterns of the project.
+
+---
+
+*Modification of these rules requires a consensus from the core engineering team.*

README.md

@@ -138,7 +138,7 @@ ask skill list                # View installed skills
 | `ask init` | Initialize project, create `ask.yaml` |
 | **Skill Management** | |
 | `ask skill search <keyword>` | Search skills across all sources |
-| `ask skill install <skill...>` | Install skill(s) to `./skills/` |
+| `ask skill install <skill...>` | Install skill(s) to `.agent/skills/` |
 | `ask skill install skill@v1.0` | Install specific version |
 | `ask skill uninstall <skill>` | Remove a skill |
 | `ask skill list` | List installed skills |

README_zh.md

@@ -112,7 +112,7 @@ ask skill list                # 查看已安装技能
 | `ask init` | 初始化项目，创建 `ask.yaml` |
 | **技能管理** | |
 | `ask skill search <关键词>` | 从所有来源搜索技能 |
-| `ask skill install <技能...>` | 安装技能到 `./skills/` |
+| `ask skill install <技能...>` | 安装技能到 `.agent/skills/` |
 | `ask skill install skill@v1.0` | 安装指定版本 |
 | `ask skill uninstall <技能>` | 移除技能 |
 | `ask skill list` | 列出已安装技能 |

docs/commands.md

@@ -67,6 +67,7 @@ ask skill install <skill>                    # Install latest version
 ask skill install <skill>@v1.0.0             # Install specific version
 ask skill install owner/repo                 # Install from GitHub repo
 ask skill install owner/repo/path/to/skill   # Install from subdirectory
+ask skill install <skill> --agent claude cursor  # Install for specific agents
 ```
 
 **Examples:**
@@ -77,8 +78,12 @@ ask skill install browser-use@v1.2.0       # Specific version
 ask skill install anthropics/skills/computer-use  # From path
 ```
 
+**Flags:**
+- `--agent, -a`: Install to specific agent(s) (claude, cursor, codex, opencode)
+- `--global, -g`: Install to global directory (~/.ask/skills)
+
 **What it does:**
-- Downloads the skill to `.agent/skills/<name>/`
+- Downloads the skill to `.agent/skills/<name>/` (or agent-specific directories)
 - Adds entry to `ask.yaml`
 - Records version info in `ask.lock`
 
@@ -104,9 +109,17 @@ ask skill uninstall <skill>
 List all installed skills.
 
 ```bash
-ask skill list
+ask skill list                   # List project skills
+ask skill list --global          # List global skills
+ask skill list --all             # List both project and global
+ask skill list --agent claude    # List skills for specific agent
 ```
 
+**Flags:**
+- `--agent, -a`: List skills for specific agent(s)
+- `--all`: Show both project and global skills
+- `--global, -g`: Show global skills only
+
 ---
 
 ### ask skill info
@@ -200,6 +213,7 @@ ask repo add my-org/skills
 
 Remove a skill source.
 
+```bash
 ask repo remove <name>
 ```