create-agent-skills 1.1.5 → 1.1.7

package/README.md

@@ -5,13 +5,13 @@ CLI tool to install Agent Skills for AI coding assistants.
 ## Installation
 
 ```bash
-npx create-agent-skills
+npx create-agent-skills@latest
 ```
 
 Or install globally:
 
 ```bash
-npm install -g create-agent-skills
+npm install -g create-agent-skills@latest
 ```
 
 ## Usage
@@ -19,7 +19,7 @@ npm install -g create-agent-skills
 Run the CLI and follow the interactive prompts:
 
 ```bash
-npx create-agent-skills
+npx create-agent-skills@latest
 ```
 
 ### Options
@@ -40,15 +40,19 @@ npx create-agent-skills
 |-------|-------------|
 | `code-review` | Reviews code for bugs, style, and security issues |
 | `create-agent-skill` | Helps create new skills following guidelines |
-| `documentation` | Creates clear READMEs, API docs, and comments |
+| `flutter-clean-arch` | Flutter Clean Architecture using BLoC, Dio, and GetIt |
 | `git-commit` | Writes conventional commit messages |
 | `git-pr` | Creates well-structured pull requests |
 | `git-review` | Reviews PRs for code quality and best practices |
-| `maestro-testing` | Write E2E tests for mobile/web apps using Maestro |
+| `landing-page-slider` | Landing pages with integrated slider for presentations |
+| `lumi-tester` | Guide for extending the Lumi Tester framework |
+| `project-documentation` | Generates comprehensive documentation for existing projects |
+| `remotion` | Create videos programmatically in React |
 | `rust-backend` | Build backend services with Rust and Clean Architecture |
 | `tailwindcss-v4` | Tailwind CSS v4 setup and migration guide |
 | `tauri-v2` | Build desktop apps with Tauri v2 + React |
 | `testing` | Helps write unit, integration, and E2E tests |
+| `threejs` | Complete Three.js development guide |
 
 ## Creating New Skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-skills",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "CLI tool to install Agent Skills for AI coding assistants",
   "main": "lib/index.js",
   "bin": {

package/skills/lumi-tester/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: lumi-tester
+description: Comprehensive guide for extending the Lumi Tester framework. Use when adding new commands, selectors, or debugging the test runner.
+---
+
+# Lumi Tester Development
+
+This skill provides a step-by-step guide for extending the Lumi Tester automation framework. It covers adding new commands, selectors, and debugging workflows.
+
+## When to Use This Skill
+
+- Use when **adding a new automation command** (e.g., `scanBarcode`, `zoomIn`).
+- Use when **adding a new selector strategy** (e.g., `barcode: "..."`, `ai_description: "..."`).
+- Use when **debugging** command execution or driver issues.
+- Use when **understanding the architecture** of `lumi-tester`.
+
+## Architecture Overview
+
+For a deep dive into the internal logic, see [Core Architecture & Internals](resources/core-architecture.md).
+
+1.  **Parser** (`src/parser/types.rs`): deserializes YAML to `TestCommand` enums.
+2.  **Executor** (`src/runner/executor.rs`): orchestrates execution, managing context (`TestContext`) and flow (`TestSessionState`). Handles logic *around* the driver (retries, logging, flow control).
+3.  **Driver Trait** (`src/driver/traits.rs`): defines the abstract `PlatformDriver` interface. Handles direct device interactions.
+4.  **Implementations** (`src/driver/<platform>/driver.rs`): concrete implementations for Android (ADB), iOS (IDB/WDA), and Web (Playwright).
+
+## How to use
+
+### Workflow 1: Add a New Command
+
+Follow this strict order to ensure all layers are covered.
+
+#### Step 1: Define Parser (`src/parser/types.rs`)
+
+1.  Add a `struct` for your command parameters (if it takes arguments).
+    ```rust
+    #[derive(Debug, Clone, Serialize, Deserialize)]
+    #[serde(rename_all = "camelCase")] // Ensures camelCase in YAML maps to struct fields
+    pub struct MyNewCommandParams {
+        pub target: String,
+        #[serde(default)]
+        pub duration: Option<u64>,
+        /// Optional label for custom logging (e.g., "Press Login Button")
+        #[serde(default)]
+        pub label: Option<String>,
+    }
+    ```
+2.  Add a variant to the `TestCommand` enum.
+    ```rust
+    #[derive(Debug, Clone, Serialize, Deserialize)]
+    #[serde(rename_all = "camelCase")]
+    pub enum TestCommand {
+        // ...
+        #[serde(alias = "myCmd")] // Optional alias for YAML convenience
+        MyNewCommand(MyNewCommandParams), // or MyNewCommand, if no params
+    }
+    ```
+
+#### Step 2: Define Interface (`src/driver/traits.rs`)
+
+1.  Add the method signature to the `PlatformDriver` trait.
+    ```rust
+    #[async_trait]
+    pub trait PlatformDriver: Send + Sync {
+        // ...
+        async fn my_new_command(&self, target: &str, duration: Option<u64>) -> Result<()>;
+    }
+    ```
+2.  (Optional) Provide a default implementation returning `Err("Not implemented")` if it's not supported on all platforms immediately.
+
+#### Step 3: Integrate Executor (`src/runner/executor.rs`)
+
+1.  Locate `async fn execute_command`.
+2.  Add a match arm for your new command variant.
+    ```rust
+    TestCommand::MyNewCommand(params) => {
+        println!("  {} Executing MyNewCommand...", "➤".blue());
+        // Verify selector if needed
+        // let selector = self.build_selector(..., params.ocr, ...)?;
+        self.driver.my_new_command(&params.target, params.duration).await?;
+    }
+    ```
+
+#### Step 4: Implement Driver Logic (`src/driver/<platform>/driver.rs`)
+
+Implement the trait method for **EACH** supported platform (`android`, `ios`, `web`).
+
+**Android (`src/driver/android/driver.rs`):**
+```rust
+async fn my_new_command(&self, target: &str, duration: Option<u64>) -> Result<()> {
+    // Use adb or uiautomator
+    adb::exec_command(&self.serial, &["shell", "input", ...]).await?;
+    Ok(())
+}
+```
+
+**iOS (`src/driver/ios/driver.rs`):**
+```rust
+async fn my_new_command(&self, target: &str, duration: Option<u64>) -> Result<()> {
+    // Use idb or WDA
+    self.wda_client.lock().await.perform_action(...).await?;
+    Ok(())
+}
+```
+
+**Web (`src/driver/web/driver.rs`):**
+```rust
+async fn my_new_command(&self, target: &str, duration: Option<u64>) -> Result<()> {
+    let page = self.page.lock().await;
+    page.evaluate_js(...).await?;
+    Ok(())
+}
+```
+
+#### Step 5: Update Documentation (`docs/commands.md`)
+
+Add your new command to `lumi-tester/docs/commands.md`.
+- Add to the Table of Contents if necessary.
+- Add a new section with **Description**, **Example YAML**, and **Parameters Table**.
+
+#### Step 6: Update VS Code Extension (`lumi-tester-vscode`)
+
+Update `src/schema/commands.ts` in the `lumi-tester-vscode` repo to enable IntelliSense.
+
+1.  Add a new object to the `LUMI_COMMANDS` array:
+    ```typescript
+    {
+      name: 'myNewCommand',
+      category: 'Interaction', // or 'App Management', 'Control Flow'...
+      description: 'Description of what it does',
+      hasParams: true,
+      snippet: 'myNewCommand:\n    target: "$1"', // VS Code snippet
+      params: [
+        { name: 'target', type: 'string', description: 'Target element' },
+        { name: 'duration', type: 'number', description: 'Duration in ms' },
+        // For complex objects, use a rich snippet in the param definition:
+        {
+          name: 'ocr',
+          type: 'object',
+          description: 'Find by OCR',
+          snippet: 'ocr:\n    text: "${1:text_to_find}"\n    region: "${2|all,center|}"'
+        }
+      ]
+    },
+    ```
+
+    > [!TIP]
+    > **Rich Snippets**: For complex object parameters (like `ocr`, `permissions`), add a `snippet` field to the parameter definition. This allows users to tab through properties (e.g., `text`, `region`) instead of just getting a generic completion.
+
+Selectors allow finding elements in different ways (Text, ID, OCR, etc.).
+
+#### Step 1: Define Selector (`src/driver/traits.rs`)
+
+Add a variant to the `Selector` enum.
+
+```rust
+#[derive(Debug, Clone, PartialEq)]
+pub enum Selector {
+    // ...
+    MySelector(String, usize), // args: query, index
+}
+```
+
+#### Step 2: Update Parameter Structs (`src/parser/types.rs`)
+
+If your selector needs specific parameters in command definitions (like `ocr: true` or `ocr: { text: ... }`), update the relevant parameter structs (e.g., `TapParams`, `AssertParams`).
+
+```rust
+pub struct TapParams {
+    // ...
+    pub my_selector: Option<String>,
+}
+```
+
+#### Step 3: Builder Logic (`src/runner/executor.rs`)
+
+Update the `build_selector` function signature and logic.
+
+1.  Update function signature to accept your new parameter.
+2.  Add logic to build the `Selector`.
+
+```rust
+fn build_selector(
+    // ... existing params
+    my_param: &Option<String>, // Add your new param here
+) -> Result<Selector> {
+    // ...
+    if let Some(query) = my_param {
+        return Ok(Selector::MySelector(query.clone(), 0));
+    }
+    // ...
+}
+```
+
+> [!IMPORTANT]
+> You MUST update **ALL** call sites of `build_selector` in `executor.rs` (e.g., inside `TapOn`, `AssertVisible`, etc.) to pass the new parameter. Usually pass `&None` or `&params.my_param`.
+
+#### Step 4: Implement Finding Logic (`src/driver/<platform>/driver.rs`)
+
+Update `find_element` (or equivalent internal finder) for each platform.
+
+**Android:**
+- Handle `Selector::MySelector` in `find_node_by_selector` (XML parsing) or `find_element` (UIA/OCR).
+
+**iOS:**
+- Handle `Selector::MySelector` in `find_element_internal`. Map to `idb` predicates or WDA class chains if possible.
+
+**Web:**
+- Update `selector_to_playwright` in `src/driver/web/driver.rs` to convert your selector to a Playwright-compatible string (CSS/XPath) OR handle it manually in `find_element`.
+
+### Workflow 3: Modifying Existing Commands
+
+If you add a field to an existing command struct (e.g., adding `label` to `TapParams`):
+
+#### Step 1: Update Struct (`src/parser/types.rs`)
+Add the field with `#[serde(default)]` if optional.
+
+```rust
+pub struct TapParams {
+    // ...
+    #[serde(default)]
+    pub label: Option<String>,
+}
+```
+
+> [!WARNING]
+> **CRITICAL: Check for Manual Parsing (`src/parser/yaml.rs`)**
+> Some commands (like `LaunchApp`, `TapOn`) are **manually constructed** in `src/parser/yaml.rs` inside `parse_command_with_params`.
+> If you add a field to the struct, you **MUST** update the initialization logic in `yaml.rs`.
+>
+> **Also Check**: `impl Default` blocks in `src/parser/types.rs`. If you add a field, update the default implementation.
+
+#### Step 2: Update Usage
+Update `executor.rs` or `driver` implementations to use the new field.
+
+#### Step 3: Update Docs & VS Code
+1.  **Docs**: Update the parameter table in `docs/commands.md`.
+2.  **VS Code**: Add the new parameter to the `params` array in `lumi-tester-vscode/src/schema/commands.ts`.
+
+> [!IMPORTANT]
+> **Standardize Selectors**: If you add a new selector (e.g., `ocr`, `role`, `desc`) to `tap`, you **MUST** also add it to **ALL** other interaction and assertion commands that use selectors:
+> - **Interactions**: `doubleTap`, `longPress`, `rightClick`, `type`, `tapAt`
+> - **Scroll**: `scrollTo`, `scrollUntilVisible`
+> - **Assertions**: `see`, `notSee`, `waitUntilVisible`, `waitNotSee`
+>
+> Failure to do this results in inconsistent autocomplete and frustrates users who expect the new selector to work everywhere.
+
+## Logging & Debugging
+
+### Logging Guidelines
+- **User-Facing Logs**: Use `println!` with colored output for high-level steps (e.g., `➤ Executing...`).
+    - **Info**: `println!("{}", "➤ Message".blue())`
+    - **Success**: `println!("{}", "✓ Message".green())`
+    - **Error**: `println!("{}", "✗ Message".red())`
+- **Debug Logs**: Use the `log` crate macros (`debug!`, `trace!`). These are hidden by default and only show when `RUST_LOG=debug` is set.
+    - **DO NOT** use `println!` for internal details.
+    - Example:
+      ```rust
+      // In your driver or executor
+      log::debug!("Finding element with selector: {:?}", selector);
+      ```
+
+## Examples
+
+- [Adding a Zoom Command](examples/add-zoom-command.md): End-to-end walkthrough of adding a new command across all layers.
+
+## Troubleshooting
+
+- **Common Issues**: See [Common Pitfalls & Troubleshooting](resources/common-pitfalls.md) for detailed solutions to parsing and execution errors.
+- **Logs**: Use `println!` with colored output (`"msg".blue()`) for visibility.
+    - Blue: Info/Action (`"➤ Executing..."`)
+    - Cyan: Detail (`"  Tap at..."`)
+    - Yellow: Warning
+    - Red: Error
+- **Run with Trace**: `RUST_LOG=trace cargo run ...`
+- **Output Dir**: Check the output directory (default `test_output/<timestamp>/`) for screenshots and logs.
+- **Unit Tests**: Create a small unit test in the driver file to verify specific logic (e.g., regex parsing) without running a full simulator.
+
+## Checklist for Success
+
+- [ ] **Parser**: Did you add `struct` and `TestCommand` variant with correct `serde` attributes?
+- [ ] **Executor**: Did you add the `match` arm? Did you update `build_selector` calls if needed?
+- [ ] **Trait**: Did you add the method to `PlatformDriver`?
+- [ ] **Impl**: Did you implement it for **Android**, **iOS**, and **Web**? (Or use `unimplemented!()`).
+- [ ] **Legacy Init**: If modifying an existing command, did you check `src/parser/yaml.rs` for manual initialization?
+- [ ] **Docs**: Did you update `docs/commands.md`?
+- [ ] **VS Code**: Did you update `lumi-tester-vscode/src/schema/commands.ts`?
+- [ ] **Build**: Run `cargo check` to catch missing implementations.
+- [ ] **Test**: Verify with a minimal YAML file.

package/skills/lumi-tester/examples/add-zoom-command.md

@@ -0,0 +1,82 @@
+# Example: Adding a `zoomIn` Command
+
+This example demonstrates the complete workflow for adding a `zoomIn` command to `lumi-tester`.
+
+## 1. Parser (`src/parser/types.rs`)
+
+Add parameter struct and enum variant.
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ZoomParams {
+    pub scale: f32, // e.g., 2.0 for 2x
+    #[serde(default)]
+    pub duration_ms: Option<u64>,
+}
+
+pub enum TestCommand {
+    // ...
+    #[serde(alias = "zoom")]
+    ZoomIn(ZoomParams),
+}
+```
+
+## 2. Driver Trait (`src/driver/traits.rs`)
+
+Add abstract method.
+
+```rust
+#[async_trait]
+pub trait PlatformDriver: Send + Sync {
+    // ...
+    async fn zoom_in(&self, scale: f32, duration_ms: Option<u64>) -> Result<()>;
+}
+```
+
+## 3. Executor (`src/runner/executor.rs`)
+
+Connect parser to driver.
+
+```rust
+async fn execute_command(&mut self, command: &TestCommand) -> Result<()> {
+    match command {
+        // ...
+        TestCommand::ZoomIn(params) => {
+            println!("  {} Zooming in (scale: {})...", "🔍".blue(), params.scale);
+            self.driver.zoom_in(params.scale, params.duration_ms).await?;
+        }
+    }
+}
+```
+
+## 4. Driver Implementation (`src/driver/*/driver.rs`)
+
+### Android (`android/driver.rs`) using pinch gesture
+```rust
+async fn zoom_in(&self, scale: f32, duration_ms: Option<u64>) -> Result<()> {
+    // Complex gesture: using adb shell input swipe with 2 pointers is hard.
+    // Better to use `adb exec-out uiautomator` or accessibility service if available.
+    // For simplicity, let's say we implement a basic center-out swipe.
+    println!("    {} Android zoom not fully implemented, simulating...", "⚠️".yellow());
+    Ok(())
+}
+```
+
+### iOS (`ios/driver.rs`) using WDA
+```rust
+async fn zoom_in(&self, scale: f32, duration_ms: Option<u64>) -> Result<()> {
+    // WDA has pinch method
+    self.wda_client.lock().await.perform_pinch(scale, ...).await?;
+    Ok(())
+}
+```
+
+### Web (`web/driver.rs`) using CSS
+```rust
+async fn zoom_in(&self, scale: f32, duration_ms: Option<u64>) -> Result<()> {
+    let page = self.page.lock().await;
+    page.evaluate::<_, ()>("scale => document.body.style.zoom = scale", scale).await?;
+    Ok(())
+}
+```

package/skills/lumi-tester/resources/common-pitfalls.md

@@ -0,0 +1,58 @@
+# Common Pitfalls & Troubleshooting
+
+This guide addresses frequent issues encountered when extending `lumi-tester`.
+
+## 1. Parser Issues (YAML -> Rust)
+
+### Issue: "unknown field" error parsing YAML
+**Cause:** Mismatch between YAML field names and Rust struct fields.
+**Solution:**
+- Ensure `#[serde(rename_all = "camelCase")]` is on your struct.
+- Verify you aren't using snake_case in YAML if Rust expects camelCase.
+- Use `#[serde(alias = "oldName")]` for backward compatibility.
+
+### Issue: Enum variant not matching
+**Cause:** `TestCommand` enum parsing is sensitive to case or aliases.
+**Solution:**
+- Check `#[serde(alias = "...")]` on the enum variant.
+- Remember `rename_all="camelCase"` applies to variants too (e.g., `MyCommand` becomes `myCommand` in YAML).
+
+### Issue: "missing field" compilation error in `yaml.rs`
+**Cause:** You added a field to a struct in `types.rs`, but `src/parser/yaml.rs` manually initializes this struct without the new field.
+**Solution:**
+- Open `src/parser/yaml.rs`.
+- Search for the struct name (e.g., `LaunchAppParams`).
+- Add the missing field to the initialization block (usually `field: None` or `Default::default()`).
+
+### Issue: "missing field" in `Default` impl
+**Cause:** The struct implements `Default` manually in `types.rs`, and you didn't update it.
+**Solution:** Find `impl Default for MyStruct` in `types.rs` and add the new field.
+
+## 2. Executor Issues
+
+### Issue: "No selector specified" panic
+**Cause:** `build_selector` called with `&None` for all selector fields.
+**Solution:** ensure your new selector parameter is passed correctly and `build_selector` logic handles it (returns `Ok(Selector::...)`).
+
+### Issue: Command executes but does nothing
+**Cause:** Driver implementation might be empty or returning `Ok(())` without action.
+**Solution:** Add println logs (`"➤ Executing..."`) inside the driver implementation to verify it's reached.
+
+## 3. Playwright/Web Issues
+
+### Issue: Selector works in Inspector but not in Test
+**Cause:** Shadow DOM or dynamic ID visibility.
+**Solution:**
+- Use `page.locator()` methods which wait for visibility.
+- Ensure `selector_to_playwright` produces valid CSS/XPath.
+- For custom selectors (OCR/Image), ensure the helper returns coordinates properly.
+
+## 4. Compilation Errors
+
+### Issue: `method not found in ...`
+**Cause:** Forgot to add method to `PlatformDriver` trait OR implement it in one of the drivers.
+**Solution:** Check `src/driver/traits.rs` first. Then check implementations.
+
+### Issue: `struct has missing field` in `build_selector` call
+**Cause:** You updated `build_selector` signature but didn't update all call sites.
+**Solution:** The compiler will point to every call site (TapOn, AssertVisible, etc.). You must update ALL of them.

package/skills/lumi-tester/resources/core-architecture.md

@@ -0,0 +1,51 @@
+# Core Architecture & Internals
+
+This document explains the internal working of `lumi-tester` to assist with maintenance and core refactoring.
+
+## 1. Execution Flow (`Executor`)
+
+ The `TestExecutor` (`src/runner/executor.rs`) is the heart of the runner.
+
+### Lifecycle of a Test Run
+1.  **Parsing**: `parse_test_file` (in `parser/yaml.rs`) converts YAML -> `TestFlow` struct.
+2.  **Initialization**: `TestExecutor::new` creates:
+    -   `TestContext`: Holds variables, app ID, platform-specific configs.
+    -   `TestSessionState`: Tracks overall progress.
+    -   `EventEmitter`: Async channel for reporting events (logs, status updates).
+3.  **Flow Execution** (`run_file` -> `run_commands_set`):
+    -   **Context Update**: Merges flow-specific header configs.
+    -   **DDT Loop**: If `data` (CSV) is present, iterates over rows, injecting variables.
+    -   **Command Loop**: Iterates through `TestCommand`s.
+        -   **State Tracking**: Updates `CommandState` (Running -> Passed/Failed).
+        -   **Event Emission**: Emits `CommandStarted`, `CommandPassed`, `CommandFailed`.
+        -   **Error Handling**: Catches errors from `execute_command`.
+            -   *Soft Errors*: Logged but don't stop flow (unless `continueOnFailure` is false).
+            -   *Hard Errors*: Stop execution immediately.
+
+## 2. State Management (`State`)
+
+State is managed hierarchically in `src/runner/state.rs`:
+
+-   **TestSessionState**: Root level. Contains multiple `FlowState`s.
+-   **FlowState**: Represents one test file execution (or one DDT iteration). Contains `CommandState`s.
+-   **CommandState**: Individual command status (Pending, Running, Passed, Failed).
+
+> **Maintenance Tip**: When adding new execution logic (e.g., `retry`), update `CommandStatus` enum and handle state transitions in `executor.rs`.
+
+## 3. Driver Architecture
+
+The `PlatformDriver` trait (`src/driver/traits.rs`) enforces consistency.
+
+-   **Lazy Initialization**: Drivers (especially iOS/Web) often use `OnceCell` for expensive resources (WDA client, Browser instance).
+-   **Thread Safety**: Drivers must be `Send + Sync` to work with async runtime.
+-   **Selector Handling**: `find_element` is usually the choke point.
+    -   *Android*: Parsing XML hierarchy from `adb exec-out uiautomator`.
+    -   *iOS*: `idb` UI tree or WDA predicate string.
+    -   *Web*: Playwright selector engine.
+
+## 4. Testing Strategy
+
+To safely refactor core logic:
+1.  **Unit Tests**: located in `src/driver/*/mod.rs` or alongside source. Run with `cargo test`.
+2.  **E2E Verification**: Use the `my_testing/` folder YAMLs.
+    -   Run `cargo run -- run my_testing/android/demo.yaml --platform android` for regression testing.

package/skills/project-documentation/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: project-documentation
+description: Automatically generates comprehensive documentation (Overview, Architecture, Flows) for an existing project by analyzing code and identifying flows. Supports all languages (Python, JS/TS, Flutter, Swift, C++, Rust, etc.).
+---
+
+# Project Documentation Generation Skill
+
+This skill allows you to reverse-engineer an existing codebase to create high-quality, comprehensive documentation. It supports **Multi-Language Analysis** (C++, Java, Kotlin, Swift, Dart, Go, Rust, etc.) using a custom Python script.
+
+## When to Use This Skill
+
+-   **Legacy Code**: Documenting undocumented projects.
+-   **Onboarding**: Creating specific "Feature Guides" or "Architecture Overviews".
+-   **Review**: Generating a "Current State" report before starting a refactor.
+
+## Skill Structure
+```text
+.agent/skills/project-documentation/
+├── SKILL.md                          # Main instructions
+├── scripts/
+│   └── analyze_codebase.py           # Analysis script (Python)
+├── resources/
+│   ├── standards.md                  # Documentation Standards (REQUIRED)
+│   └── templates/
+│       ├── flow.md                   # Template for Business Flows (Logic)
+│       ├── feature_guide.md          # Template for UI/Screens
+│       └── technical_reference.md    # Template for Backend/API
+└── examples/
+    └── example_usage.md              # Complete walkthrough
+```
+
+## Prerequisites
+
+-   Python 3 installed.
+-   Read access to the project root directory.
+-   **REQUIRED**: Read the [Documentation Standards](./resources/standards.md) before writing any docs.
+    ```bash
+    view_file ./resources/standards.md
+    ```
+
+## How to Use
+
+### Step 1: Run Analysis
+
+Always run the script first to map the project.
+```bash
+# Run from the root of the project you want to document
+# Note: The script is located in the skill's scripts directory
+python3 ./scripts/analyze_codebase.py . > codebase_analysis.md
+```
+
+### Step 2: Create Checklist (Modular Plan)
+
+You **MUST** create `documentation_checklist.md` assuming a modular structure:
+-   [ ] **`docs/README.md`**: Index and Overview.
+-   [ ] **`docs/setup.md`**: Installation instructions.
+-   [ ] **`docs/architecture.md`**: System diagrams.
+-   [ ] **`docs/flows/*.md`**: Business Logic Flows (CRITICAL).
+-   [ ] **`docs/api/*.md`**: API Reference (Low-level).
+-   [ ] **`docs/troubleshooting.md`**: Common issues.
+
+### Step 3: Scaffold & Write
+
+1.  Create the directory structure:
+    ```bash
+    mkdir -p docs/api docs/flows
+    ```
+2.  Write each file using the appropriate template from the Resources section.
+
+## Workflows
+
+### Workflow 1: Backend / General
+*Best for: Server code (Go, Rust, Node.js), CLI tools.*
+-   **Focus**: Endpoints, Database Schema, Data Models.
+-   **Structure**:
+    -   `docs/api/[module].md` (Use [Technical Reference](./resources/templates/technical_reference.md))
+    -   `docs/flows/[flow_name].md` (Use [Flow Template](./resources/templates/flow.md))
+    -   `docs/architecture.md` (Use [Architecture Template](./resources/templates/architecture.md))
+
+### Workflow 2: Mobile App
+*Best for: Flutter, Swift, Kotlin, React Native.*
+-   **Focus**: User Flows, Navigation, State Logic.
+-   **Structure**:
+    -   `docs/flows/[feature].md` (Use [Flow Template](./resources/templates/flow.md))
+    -   `docs/setup.md` (Use [Setup Template](./resources/templates/setup.md))
+
+### Workflow 3: Embedded / Legacy
+*Best for: C/C++, Java, Embedded Systems.*
+-   **Focus**: Hardware Interactions, Memory Flows.
+-   **Structure**:
+    -   `docs/architecture.md` (Use [Architecture Template](./resources/templates/architecture.md))
+    -   `docs/flows/[process].md` (Use [Flow Template](./resources/templates/flow.md))
+
+## Examples
+
+-   [Documenting a Flutter App](./examples/example_usage.md) - A complete walkthrough.
+
+## Resources
+
+-   [Standards & Guidelines](./resources/standards.md)
+-   [Flow Template (Logic Traces)](./resources/templates/flow.md)
+-   [Technical Reference Template](./resources/templates/technical_reference.md)
+-   [Feature Guide Template](./resources/templates/feature_guide.md)
+
+## Best Practices
+
+-   **Visuals First**: Always draw the Flow/Architecture before writing text.
+-   **Link to Code**: Use specific filenames from the analysis in your docs.
+-   **Keep it Portable**: Use relative paths in your generated documentation where possible.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Script not found | Ensure you are running the `python3` command relative to the skill directory or copy the script to your project root. |
+| Output is empty | Check if the language extension is supported. The script supports .py, .js, .ts, .rs, .go, .java, .kt, .swift, .c, .cpp, .dart. |
+| Diagram Errors | Start with a simple graph. Complex mermaid often breaks markdown viewers. |