chore: import upstream snapshot with attribution

docs/customization/cline-rules.mdx

@@ -0,0 +1,396 @@
+---
+title: "Rules"
+sidebarTitle: "Rules"
+description: "Define specific instructions and coding standards for Cline."
+---
+
+Rules are markdown files that provide persistent instructions across all conversations. Instead of repeating the same preferences every time you start a new task, rules let you define them once and have Cline follow them automatically.
+
+Use rules when you want Cline to:
+- Follow your team's coding standards (naming conventions, file organization, error handling patterns)
+- Understand project-specific context (tech stack, architecture decisions, dependencies)
+- Apply consistent documentation or testing requirements
+- Remember constraints like "don't modify files in /legacy" or "always use TypeScript"
+
+<Tip>
+  **New to Rules?** Watch [Cline Rules Explained](https://youtu.be/xQwsy2vkK5M) to see them in action.
+</Tip>
+
+
+## Supported Rule Types
+
+Cline recognizes rules from multiple sources, so you can use existing rule files from other tools:
+
+| Rule Type | Location | Description |
+|-----------|----------|-------------|
+| Cline Rules | `.clinerules/` | Primary rule format |
+| Cursor Rules | `.cursorrules` | Automatically detected |
+| Windsurf Rules | `.windsurfrules` | Automatically detected |
+| AGENTS.md | `AGENTS.md`, `~/.agents/AGENTS.md` | [Standard format](https://agents.md/) for cross-tool compatibility |
+
+All detected rule types appear in the Rules panel, where you can toggle them individually.
+
+
+## Where Rules Live
+
+Rules can be stored in two locations: your project workspace or globally on your system.
+
+**Workspace rules** go in `.clinerules/` at your project root. Use these for team standards, project-specific constraints, and anything you want to share with collaborators via version control.
+
+**Global rules** go in your system's Cline Rules directory. Use these for personal preferences that apply across all projects. Cline also reads cross-tool global AGENTS instructions from `~/.agents/AGENTS.md`.
+
+```text
+your-project/
+├── .clinerules/              # Workspace rules
+│   ├── coding.md             # Coding standards
+│   ├── testing.md            # Test requirements
+│   └── architecture.md       # Structural decisions
+├── src/
+└── ...
+```
+
+Cline processes all `.md` and `.txt` files inside `.clinerules/`, combining them into a unified set of rules. Numeric prefixes (like `01-coding.md`) help organize files but are optional.
+
+When both workspace and global rules exist, Cline combines them. Workspace rules take precedence when they conflict with global rules. See [Storage Locations](/getting-started/config#storage-locations) for more guidance.
+
+### Global Rules Directory
+
+| Operating System | Default Location |
+|------------------|------------------|
+| Windows | `Documents\Cline\Rules` |
+| macOS | `~/Documents/Cline/Rules` |
+| Linux/WSL | `~/Documents/Cline/Rules` |
+
+<Note>
+Linux/WSL users: If you don't find global rules in `~/Documents/Cline/Rules`, check `~/Cline/Rules`.
+</Note>
+
+
+## Creating Rules
+
+<Steps>
+  <Step title="Open the Rules menu">
+    Click the scale icon at the bottom of the Cline panel, to the left of the model selector.
+  </Step>
+  <Step title="Create a new rule file">
+    Click "New rule file..." and enter a filename (e.g., `coding-standards`). The file will be created with a `.md` extension.
+  </Step>
+  <Step title="Write your rule">
+    Add your instructions in markdown format. Keep each rule file focused on a single concern.
+  </Step>
+</Steps>
+
+You can also use the [`/newrule` slash command](/core-workflows/using-commands#newrule) to have Cline create a rule interactively.
+
+### Toggling Rules
+
+Every rule has a toggle to enable or disable it. This gives you fine-grained control over which rules apply to your current task without deleting the rule file.
+
+For example, you might have a strict testing rule that you want to disable when prototyping, or a client-specific rule you only need when working on that client's features.
+
+## Writing Effective Rules
+
+### Structure
+
+Rules work best when they're scannable and specific. Use markdown structure to organize instructions:
+
+```markdown
+# Rule Title
+
+Brief context about why this rule exists (optional but helpful).
+
+## Category 1
+- Specific instruction
+- Another instruction with example: `like this`
+- Reference to file: see /src/utils/example.ts
+
+## Category 2
+- More instructions
+- Include the "why" when it's not obvious
+```
+
+Cline reads rules as context, so formatting matters. Headers help Cline understand the scope of each instruction. Bullet points make individual requirements clear. Code examples show exactly what you want.
+
+### Best Practices
+
+**Be specific, not vague.** "Use descriptive variable names" is too broad. "Use camelCase for variables, PascalCase for classes, UPPER_SNAKE for constants" gives Cline something concrete to follow.
+
+**Include the why.** When a rule might seem arbitrary, explain the reason. "Don't modify files in /legacy (this code is scheduled for removal in Q2)" helps Cline make better decisions in edge cases.
+
+**Point to examples.** If your codebase already demonstrates the pattern you want, reference it. "Follow the error handling pattern in /src/utils/errors.ts" is more effective than describing the pattern from scratch.
+
+**Keep rules current.** Outdated rules confuse Cline and waste context. If a constraint no longer applies, remove it. If your tech stack changes, update the rules.
+
+**One concern per file.** Split rules by topic: `coding.md` for style, `testing.md` for test requirements, `architecture.md` for structural decisions. This makes it easy to toggle specific rules on or off.
+
+<Warning>
+Rules consume context tokens. Avoid lengthy explanations or pasting entire style guides. Keep rules concise and link to external documentation when detailed reference is needed.
+</Warning>
+
+## Example
+
+```markdown
+# Project Guidelines
+
+## Code Style
+- Use TypeScript for all new files
+- Prefer composition over inheritance
+- Use repository pattern for data access
+- Follow error handling pattern in /src/utils/errors.ts
+
+## Documentation
+- Update relevant docs when modifying features
+- Keep README.md in sync with new capabilities
+
+## Testing
+- Unit tests required for business logic
+- Integration tests for API endpoints
+- E2E tests for critical user flows
+```
+
+
+## Conditional Rules
+
+Conditional rules let you scope rules to specific parts of your codebase. Rules activate only when you're working with matching files, keeping your context focused and relevant.
+
+- **Without conditionals**: every rule loads for every request.
+- **With conditionals**, rules activate only when your current files match their defined scope.
+
+For example, documentation style rules should only appear when you're editing docs, not when you're writing application code or tests.
+
+As your rule library grows, loading every rule for every request wastes context tokens and can dilute Cline's focus. Conditional rules solve this by giving Cline only the instructions that matter for the files you're actually touching. This means faster, more accurate responses. Your frontend rules won't compete for attention when you're deep in backend code, and your testing standards appear exactly when you're writing tests. It's the difference between handing someone an entire policy manual versus the one page they need right now.
+
+### How It Works
+
+Conditional rules use YAML frontmatter at the top of your rule files. When Cline processes a request, it gathers context from your current work (open files, visible tabs, mentioned paths, edited files), evaluates each rule's conditions, and activates matching rules.
+
+<Note>
+When a conditional rule activates, you'll see a notification: **"Conditional rules applied: workspace:frontend-rules.md"**
+</Note>
+
+### Writing Conditional Rules
+
+Add YAML frontmatter to the top of any rule file in your `.clinerules/` directory:
+
+```yaml
+---
+paths:
+  - "src/components/**"
+  - "src/hooks/**"
+---
+
+# React Component Guidelines
+
+When creating or modifying React components:
+- Use functional components with React hooks
+- Extract reusable logic into custom React hooks
+- Keep components focused on a single responsibility
+```
+
+The `---` markers delimit the frontmatter. Everything after the closing `---` is your rule content.
+
+#### The `paths` Conditional
+
+Currently, `paths` is the supported conditional. It takes an array of glob patterns:
+
+```yaml
+---
+paths:
+  - "src/**"           # All files under src/
+  - "*.config.js"      # Config files in root
+  - "packages/*/src/"  # Monorepo package sources
+---
+```
+
+**Glob pattern syntax:**
+
+- `*` matches any characters except `/`
+- `**` matches any characters including `/` (recursive)
+- `?` matches a single character
+- `[abc]` matches any character in the brackets
+- `{a,b}` matches either pattern
+
+| Pattern | Matches |
+|---------|---------|
+| `src/**/*.ts` | All TypeScript files under `src/` |
+| `*.md` | Markdown files in root only |
+| `**/*.test.ts` | Test files anywhere in the project |
+| `packages/{web,api}/**` | Files in web or api packages |
+| `src/components/*.tsx` | TSX files directly in components (not nested) |
+
+#### Behavior Details
+
+**Multiple patterns**: A rule activates if any pattern matches any file in your context.
+
+```yaml
+---
+paths:
+  - "frontend/**"
+  - "mobile/**"
+---
+# Activates when working in frontend OR mobile
+```
+
+**No frontmatter**: Rules without frontmatter are always active.
+
+**Empty paths array**: `paths: []` means the rule never activates. Use this to temporarily disable a rule.
+
+**Invalid YAML**: If frontmatter can't be parsed, Cline fails open. The rule activates with raw content visible to help debugging.
+
+### What Counts as "Current Context"
+
+Cline evaluates rules based on:
+
+1. **Your message**: File paths mentioned in your prompt (e.g., "update `src/App.tsx`")
+2. **Open tabs**: Files currently open in your editor
+3. **Visible files**: Files visible in your active editor panes
+4. **Edited files**: Files Cline has created, modified, or deleted during the task
+5. **Pending operations**: Files Cline is about to edit
+
+Conditional rules can activate on your first message, when relevant files are open, or mid-task when Cline starts working with matching files.
+
+<Tip>
+Be explicit about file paths in your prompts. "Update `src/services/user.ts`" reliably triggers path-based rules; "update the user service" may not.
+</Tip>
+
+### Practical Examples
+
+Copy these patterns and adapt them to your project structure.
+
+#### Frontend vs Backend Rules
+
+Keep frontend and backend rules separate to avoid noise. Frontend rules only load when working with UI code, backend rules only load when working with API or service code.
+
+```yaml
+# .clinerules/frontend.md
+---
+paths:
+  - "src/components/**"
+  - "src/pages/**"
+  - "src/hooks/**"
+---
+
+# Frontend Guidelines
+
+- Use Tailwind CSS for styling
+- Prefer server components where possible
+- Keep client components small and focused
+```
+
+```yaml
+# .clinerules/backend.md
+---
+paths:
+  - "src/api/**"
+  - "src/services/**"
+  - "src/db/**"
+---
+
+# Backend Guidelines
+
+- Use dependency injection for services
+- All database queries go through repositories
+- Return typed errors, not thrown exceptions
+```
+
+#### Test File Rules
+
+Enforce testing standards automatically. This rule activates only when you're writing or modifying tests, so testing guidance appears exactly when you need it.
+
+```yaml
+# .clinerules/testing.md
+---
+paths:
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "**/__tests__/**"
+---
+
+# Testing Standards
+
+- Use descriptive test names: "should [expected behavior] when [condition]"
+- One assertion per test when possible
+- Mock external dependencies, not internal modules
+- Use factories for test data, not fixtures
+```
+
+#### Documentation Rules
+
+Apply documentation standards only when editing docs. Prevents style rules from cluttering your context when you're writing code.
+
+```yaml
+# .clinerules/docs.md
+---
+paths:
+  - "docs/**"
+  - "**/*.md"
+  - "**/*.mdx"
+---
+
+# Documentation Guidelines
+
+- Use sentence case for headings
+- Include code examples for all features
+- Keep paragraphs short (3-4 sentences max)
+- Link to related documentation
+```
+
+### Combining with Rule Toggles
+
+Conditional rules work alongside the rule toggle UI. Toggle off a conditional rule to disable it entirely (it won't activate even if paths match). Toggle on to let it activate when conditions are met.
+
+This provides two levels of control: manual toggles and automatic condition-based activation.
+
+### Tips for Effective Conditional Rules
+
+**Start Broad, Then Narrow.** Begin with broader patterns and refine as you learn what works:
+
+```yaml
+# Start here
+paths:
+  - "src/**"
+
+# Then narrow down
+paths:
+  - "src/features/auth/**"
+```
+
+**Use Descriptive Filenames.** Name your rule files to indicate their scope:
+
+```text
+.clinerules/
+├── api-endpoints.md      # Rules for API code
+├── database-models.md    # Rules for DB layer
+├── react-components.md   # Rules for React
+└── universal.md          # No frontmatter = always active
+```
+
+**Keep Universal Rules Separate.** Put always-on rules (coding standards, project conventions) in files without frontmatter. Reserve conditional rules for context-specific guidance.
+
+**Test Your Patterns.** Not sure if a pattern matches? Create a simple test rule:
+
+```yaml
+---
+paths:
+  - "your/pattern/here/**"
+---
+TEST: This rule should activate for your/pattern/here files.
+```
+
+Then work with a file in that path and check if you see the activation notification.
+
+### Troubleshooting Conditional Rules
+
+**Rule not activating:**
+- Check that file paths in your context match the glob pattern
+- Verify the rule is toggled on in the rules panel
+- Ensure YAML frontmatter has proper `---` delimiters
+
+**Rule activating unexpectedly:**
+- Review glob patterns. `**` is recursive and may match more than intended
+- Check for open files that match the pattern
+- File paths mentioned in your message also count as context
+
+**Frontmatter showing in output:**
+- YAML couldn't be parsed
+- Check for syntax errors (unquoted special characters, improper indentation)

docs/customization/clineignore.mdx

@@ -0,0 +1,109 @@
+---
+title: ".clineignore"
+sidebarTitle: ".clineignore"
+description: "Control which files and directories Cline can access in your project."
+---
+
+The `.clineignore` file tells Cline which files and directories to skip when analyzing your codebase. It works like `.gitignore`: create a file named `.clineignore` in your project root, add patterns for files you want excluded, and Cline will ignore them.
+
+## Why It Matters
+
+Without a `.clineignore`, Cline may load your entire project into context, including dependencies, build artifacts, and generated files. This wastes tokens, increases costs, and can push useful context out of the window.
+
+Adding a `.clineignore` can cut your starting context from 200k+ tokens to under 50k. That means faster responses, lower costs, and the ability to use smaller, cheaper models effectively.
+
+## Creating a .clineignore
+
+Create a file named `.clineignore` in your project root:
+
+```text
+# Dependencies
+node_modules/
+**/node_modules/
+
+# Build outputs
+/build/
+/dist/
+/.next/
+/out/
+
+# Testing artifacts
+/coverage/
+
+# Environment variables
+.env
+.env.*
+
+# Large data files
+*.csv
+*.xlsx
+*.sqlite
+
+# Generated/minified code
+*.min.js
+*.map
+```
+
+## Pattern Syntax
+
+`.clineignore` uses the same pattern syntax as `.gitignore`:
+
+| Pattern | Matches |
+|---------|---------|
+| `node_modules/` | The `node_modules` directory |
+| `**/node_modules/` | `node_modules` at any depth |
+| `*.csv` | All CSV files |
+| `/build/` | The `build` directory at the project root only |
+| `*.env.*` | Files like `.env.local`, `.env.production` |
+| `!important.csv` | Exception: do not ignore this file |
+
+Lines starting with `#` are comments. Blank lines are ignored.
+
+## What to Exclude
+
+Start with these categories and adjust for your project:
+
+**Almost always exclude:**
+- Package manager directories (`node_modules/`, `vendor/`, `.venv/`)
+- Build outputs (`dist/`, `build/`, `.next/`, `out/`)
+- Coverage reports (`coverage/`)
+- Lock files if large (`package-lock.json`, `yarn.lock`)
+
+**Exclude if present:**
+- Large data files (`.csv`, `.xlsx`, `.sqlite`, `.parquet`)
+- Binary assets (images, fonts, videos)
+- Generated code (API clients, protobuf outputs, minified bundles)
+- Environment files with secrets (`.env`, `.env.local`)
+
+**Keep accessible:**
+- Source code you actively work on
+- Configuration files Cline needs to understand (`tsconfig.json`, `package.json`)
+- Documentation and READMEs
+- Test files (Cline often needs these for context)
+
+## How It Works
+
+When Cline scans your project to build context, it checks each file path against your `.clineignore` patterns. Matching files are excluded from:
+
+- The file listing Cline sees when starting a task
+- Automatic context gathering during conversations
+- Search results when Cline looks for relevant code
+
+You can still reference ignored files explicitly using [@ mentions](/core-workflows/working-with-files). If you type `@/node_modules/some-package/index.js`, Cline will read that specific file even though `node_modules/` is in your `.clineignore`. The ignore rules control automatic loading, not explicit access.
+
+<Note>
+`.clineignore` is separate from `.gitignore`. Files tracked by Git but irrelevant to Cline (like large test fixtures or data files) should go in `.clineignore` even if they're not in `.gitignore`.
+</Note>
+
+## Tips
+
+- Add `.clineignore` early in your project. It's easier to start with broad exclusions and narrow them than to debug why context is bloated later.
+- Check your token usage in the task header after adding a `.clineignore`. The difference is often dramatic.
+- If Cline seems to be missing context about a file, check whether it's being excluded by your ignore patterns.
+- For monorepos or multi-root workspaces, each workspace root can have its own `.clineignore`. See [Multi-Root Workspaces](/features/multiroot-workspace) for details.
+
+## Related
+
+- [Cline Rules](/customization/cline-rules) - Define persistent instructions for Cline
+- [Task Management](/core-workflows/task-management#context-window) - Understand how context windows work
+- [Auto-Compact](/features/auto-compact) - Automatic context compression during long tasks

docs/customization/hooks.mdx

@@ -0,0 +1,7 @@
+---
+title: "Hooks"
+sidebarTitle: "Hooks"
+description: "See details under SDK Hooks page."
+---
+
+See details under [SDK Plugins](/sdk/plugins).

docs/customization/plugins.mdx

@@ -0,0 +1,147 @@
+---
+title: "Plugins"
+sidebarTitle: "Plugins"
+description: "Install and manage plugins that extend Cline with custom tools, hooks, and capabilities."
+---
+<Warning>
+  This feature currently only applies to Cline SDK, CLI, and Kanban. This feature is not applicable on VSCode and JetBrains Extension for now.
+</Warning>
+
+Plugins extend Cline with custom tools, lifecycle hooks, slash commands, and more. They can be installed globally (available in all sessions) or per-project.
+
+## Installing Plugins via CLI
+
+The `cline plugin install` command installs plugins from four source types:
+
+<Tabs>
+  <Tab title="File URL">
+    ```bash
+    cline plugin install https://github.com/owner/repo/blob/main/plugins/my-plugin.ts
+    cline plugin install https://raw.githubusercontent.com/owner/repo/main/plugins/my-plugin.ts
+    ```
+
+    File URLs install a single `.ts` or `.js` plugin file directly. GitHub `blob` and raw URLs are supported, and remote plugin file URLs must use `https://`.
+  </Tab>
+  <Tab title="Git Repository">
+    ```bash
+    cline plugin install https://github.com/owner/repo.git
+    cline plugin install git@github.com:owner/repo.git
+    ```
+
+    The installer clones the repository, installs production dependencies, and registers the plugin entry files.
+
+    To install a specific branch or tag, append `@ref`:
+
+    ```bash
+    cline plugin install https://github.com/owner/repo.git@v1.2.0
+    cline plugin install https://github.com/owner/repo.git@main
+    ```
+  </Tab>
+  <Tab title="npm Package">
+    ```bash
+    cline plugin install npm:@scope/my-plugin
+    cline plugin install --npm my-plugin
+    ```
+  </Tab>
+  <Tab title="Local Path">
+    ```bash
+    cline plugin install ./my-plugin
+    cline plugin install ~/plugins/my-tool
+    cline plugin install /absolute/path/to/plugin.ts
+    ```
+
+    Local installs copy the file or directory into the plugin store. Both single `.ts`/`.js` files and directories with a `package.json` are supported.
+  </Tab>
+</Tabs>
+
+Additional flags:
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Replace an existing install for the same source |
+| `--json` | Output the result as JSON (useful for scripting) |
+| `--cwd <path>` | Install to `<path>/.cline/plugins` instead of the global directory |
+
+After installation, confirm the plugin is loaded by running `cline config` and checking the plugin tab.
+
+### Example: TypeScript Navigation Plugin
+
+The [typescript-lsp-plugin](https://github.com/cline/typescript-lsp-plugin) is a good reference for how plugins work. It adds a `goto_definition` tool that uses the TypeScript Language Service API to resolve symbol definitions through imports, re-exports, and type aliases.
+
+Install it with:
+
+```bash
+cline plugin install https://github.com/cline/typescript-lsp-plugin.git
+```
+
+Once installed, Cline can call `goto_definition` with a file path and line number to find where symbols are defined, which is much more precise than text search.
+
+## Plugin Manifest Format
+
+For a repository or npm package to be installable as a Cline plugin, its `package.json` should include a `cline` field that declares plugin entry points:
+
+```json
+{
+  "name": "my-cline-plugin",
+  "version": "1.0.0",
+  "cline": {
+    "plugins": [
+      {
+        "paths": ["./index.ts"],
+        "capabilities": ["tools", "hooks"]
+      }
+    ]
+  }
+}
+```
+
+The `cline.plugins` array accepts:
+
+| Format | Example |
+|--------|---------|
+| Object with `paths` array | `{ "paths": ["./src/plugin.ts"], "capabilities": ["tools"] }` |
+| Plain string | `"./index.ts"` |
+
+Each path should point to a `.ts` or `.js` file that exports an `AgentPlugin` (either as the default export or a named export).
+
+If no `cline.plugins` field is present, the installer falls back to auto-discovery: it looks for standard entry points, then recursively scans for `.ts` and `.js` files (skipping `node_modules` and `.git`).
+
+### Host-Provided Dependencies
+
+Dependencies under the `@cline/` scope are provided by the host runtime. The installer automatically strips these from the plugin's dependency list before running `npm install`, so declare any `@cline/*` package your plugin imports as an optional peer dependency. The host currently provides `@cline/sdk`, `@cline/core`, `@cline/agents`, `@cline/llms`, and `@cline/shared`.
+
+```json
+{
+  "peerDependencies": {
+    "@cline/sdk": "*"
+  },
+  "peerDependenciesMeta": {
+    "@cline/sdk": {
+      "optional": true
+    }
+  }
+}
+```
+
+## Plugin Directory Structure
+
+Plugins are stored in the `plugins` directory at two levels:
+
+```
+~/.cline/
+  plugins/                     # Global plugins
+    _installed/                # Managed by `cline plugin install`
+      npm/                     # npm-sourced plugins
+      git/                     # git-sourced plugins
+      remote/                  # file URL-sourced plugins
+      local/                   # local-sourced plugins
+
+.cline/                        # Project root
+  plugins/                     # Project-scoped plugins
+```
+
+Global plugins (`~/.cline/plugins/`) are available across all sessions. Project plugins (`.cline/plugins/` in your repo) are available only when working in that project.
+
+## Writing Plugins
+
+For a guide on building plugins with the SDK, see [Writing Plugins](/sdk/guides/writing-plugins). For the plugin API reference, see [SDK Plugins](/sdk/plugins).

docs/customization/skills.mdx

@@ -0,0 +1,271 @@
+---
+title: "Skills"
+sidebarTitle: "Skills"
+description: "Modular instruction sets that extend Cline's capabilities for specific tasks."
+---
+
+Skills are modular instruction sets that extend Cline's capabilities for specific tasks. Each skill packages detailed guidance, processes, and optional resources that Cline loads only when relevant to your request.
+
+Install multiple skills and Cline only loads what it needs. A deployment skill stays dormant until you ask about deploying. Unlike [rules](/customization/cline-rules) (which are always active), skills load on-demand so they don't consume context when you're working on something unrelated.
+
+<Note>
+Manage skills from the Skills menu: click the scale icon at the bottom of the Cline panel, to the left of the model selector, then switch to the **Skills** tab.
+</Note>
+
+## How Skills Work
+
+Skills use progressive loading to maximize efficiency:
+
+| Level | When Loaded | Token Cost | Content |
+|-------|-------------|------------|---------|
+| Metadata | Always (at startup) | ~100 tokens per skill | `name` and `description` from YAML frontmatter |
+| Instructions | When skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
+| Resources | As needed | Effectively unlimited | Bundled files accessed via `read_file` or executed scripts |
+
+When you send a message, Cline sees a list of available skills with their descriptions. If your request matches a skill's description, Cline activates it using the `use_skill` tool, which loads the full instructions from SKILL.md.
+
+## Triggering Skills with Slash Commands
+
+You can also invoke enabled skills explicitly from the chat input using slash commands.
+
+1. Type `/` in chat to open command suggestions.
+2. Select the skill command you want to run (for example, `/aws-deploy`).
+3. Cline triggers that skill and loads its `SKILL.md` instructions.
+
+This is useful when you want to force a specific skill immediately instead of waiting for auto-matching based on description.
+
+## Skill Structure
+
+Every skill is a directory containing a `SKILL.md` file with YAML frontmatter.
+
+```text title="Skill directory structure"
+my-skill/
+├── SKILL.md          # Required: main instructions
+├── docs/             # Optional: additional documentation
+│   └── advanced.md
+└── scripts/          # Optional: utility scripts
+    └── helper.sh
+```
+
+The `SKILL.md` file has two parts: metadata and instructions.
+
+```markdown title="SKILL.md"
+---
+name: my-skill
+description: Brief description of what this skill does and when to use it.
+---
+
+# My Skill
+
+Detailed instructions for Cline to follow when this skill is activated.
+
+## Steps
+1. First, do this
+2. Then do that
+3. For advanced usage, see [advanced.md](docs/advanced.md)
+```
+
+Required fields:
+- `name` must exactly match the directory name
+- `description` tells Cline when to use this skill (max 1024 characters)
+
+## Creating a Skill
+
+<Steps>
+  <Step title="Open the Skills menu">
+    Click the scale icon at the bottom of the Cline panel, to the left of the model selector. Switch to the Skills tab.
+  </Step>
+  <Step title="Create a new skill">
+    Click "New skill..." and enter a name for your skill (e.g., `aws-deploy`). Cline creates a skill directory with a template `SKILL.md` file.
+  </Step>
+  <Step title="Write your skill instructions">
+    Edit the `SKILL.md` file:
+    - Update the `description` field to specify when this skill should trigger
+    - Add detailed instructions in the body
+    - Optionally add supporting files in `docs/`, `templates/`, or `scripts/` subdirectories
+  </Step>
+</Steps>
+
+You can also create skills manually by creating the directory structure in your file system. Place skill directories in `.cline/skills/` (workspace) or `~/.cline/skills/` (global) and Cline will detect them automatically.
+
+Put the important information first in your SKILL.md. Cline reads the file sequentially, so front-load the common cases. Use clear section headers like "## Error Handling" or "## Configuration" so Cline can scan for relevant sections.
+
+### Toggling Skills
+
+Every skill has a toggle to enable or disable it. This lets you control which skills are active without deleting the skill directory. Skills are enabled by default when discovered.
+
+For example, you might disable a CI/CD skill when working on local development, or enable a client-specific skill only when working on that client's project.
+
+## Writing Your SKILL.md
+
+### Naming Conventions
+
+The skill name appears in the `name` field and must match the directory name exactly. Use lowercase with hyphens (kebab-case) and be descriptive about what the skill does.
+
+Good names:
+- `aws-cdk-deploy`
+- `pr-review-checklist`
+- `database-migration`
+- `api-client-generator`
+
+Avoid:
+- `aws` (too vague)
+- `my_skill` (underscores, not descriptive)
+- `DeployToAWS` (use kebab-case, not PascalCase)
+- `misc-helpers` (too generic)
+
+### Writing Effective Descriptions
+
+The description determines when Cline activates the skill. A vague description means the skill won't trigger when you expect it to.
+
+Good descriptions are specific and actionable:
+
+```yaml
+description: Deploy applications to AWS using CDK. Use when deploying, updating infrastructure, or managing AWS resources.
+
+description: Generate release notes from git commits. Use when preparing releases, writing changelogs, or summarizing recent changes.
+
+description: Analyze CSV and Excel data files. Use when exploring datasets, generating statistics, or creating visualizations from tabular data.
+```
+
+Weak descriptions leave too much ambiguity:
+
+```yaml
+description: Helps with AWS stuff.
+
+description: Data analysis helper.
+
+description: Useful for releases.
+```
+
+Start with what the skill does (action verbs), include trigger phrases users might say, and mention specific file types, tools, or domains. Test your descriptions by trying different phrasings of requests to see if the skill triggers.
+
+### Keeping Skills Focused
+
+Keep SKILL.md under 5k tokens. If your skill needs more content, split it into separate files in a `docs/` directory and reference them from the main instructions. Cline loads referenced files only when needed.
+
+Include real examples. Show what commands to run, what output to expect, and what the result should look like. Abstract instructions are harder to follow than concrete examples.
+
+## Where Skills Live
+
+Skills can be stored globally or in a project workspace. See [Storage Locations](/getting-started/config#storage-locations) for guidance on when to use each.
+
+Project skills:
+- `.cline/skills/` (recommended)
+- `.clinerules/skills/`
+- `.claude/skills/`
+
+Global skills:
+- `~/.cline/skills/` (macOS/Linux)
+- `C:\Users\USERNAME\.cline\skills\` (Windows)
+
+When a global skill and project skill have the same name, the global skill takes precedence. This lets you keep general-purpose skills globally while using project-specific skills in `.cline/skills/` so the whole team can use them.
+
+Version control your project skills by committing `.cline/skills/`. Your team can share, review, and improve them together.
+
+## Bundling Supporting Files
+
+Skills can include additional files that Cline accesses only when needed.
+
+```text title="Directory structure"
+complex-skill/
+├── SKILL.md
+├── docs/
+│   ├── setup.md
+│   └── troubleshooting.md
+├── templates/
+│   └── config.yaml
+└── scripts/
+    └── validate.py
+```
+
+### docs/
+
+Use docs for information that's too detailed for SKILL.md or only relevant in specific situations:
+- Advanced configuration options
+- Troubleshooting guides for edge cases
+- Reference material (API schemas, database schemas)
+- Platform-specific instructions
+
+A deployment skill might have `docs/aws.md`, `docs/gcp.md`, and `docs/azure.md`. Cline loads only the relevant platform guide based on your request.
+
+### templates/
+
+Use templates when your skill creates configuration files, boilerplate code, or structured documents:
+- Config files (Terraform, Docker Compose, CI/CD pipelines)
+- Code scaffolding (component templates, test fixtures)
+- Documentation templates (README, API docs)
+
+A project setup skill could include `templates/dockerfile`, `templates/docker-compose.yml`, and `templates/.env.example` that Cline customizes for each new project.
+
+### scripts/
+
+Use scripts for deterministic operations where you want consistent behavior:
+- Validation (linting configs, checking prerequisites)
+- Data processing (parsing, formatting, transforming)
+- Complex calculations (cost estimation, resource sizing)
+- API interactions (fetching data, running health checks)
+
+Scripts are token-efficient because only their output enters context, not the code itself. A 500-line validation script produces a simple "Passed" or detailed error messages without consuming any context for the script logic.
+
+### Referencing Bundled Files
+
+Reference these files in your SKILL.md instructions:
+
+```markdown title="SKILL.md (referencing bundled files)"
+For initial setup, follow [setup.md](docs/setup.md).
+Use the config template at `templates/config.yaml` as a starting point.
+Run the validation script to check your configuration:
+
+python scripts/validate.py
+```
+
+Cline reads documentation files using `read_file` when the instructions reference them. Scripts can be executed directly, and only the script's output enters the context window.
+
+| Use Scripts For | Use Instructions For |
+|-----------------|---------------------|
+| Deterministic operations (validation, formatting) | Flexible guidance that adapts to context |
+| Complex computations | Decision-making processes |
+| Operations that need reliability | Steps that might vary by situation |
+| Anything you'd rather not consume tokens explaining | Best practices and patterns |
+
+## Example: Data Analysis Skill
+
+Here's a practical skill for data analysis tasks. Create a directory called `data-analysis/` with this `SKILL.md`:
+
+```markdown title="data-analysis/SKILL.md"
+---
+name: data-analysis
+description: Analyze data files and generate insights. Use when working with CSV, Excel, or JSON data files that need exploration, cleaning, or visualization.
+---
+
+# Data Analysis
+
+When analyzing data files, follow this process:
+
+## 1. Understand the Data
+- Read a sample of the file to understand its structure
+- Identify column types and data quality issues
+- Note any missing values or anomalies
+
+## 2. Ask Clarifying Questions
+Before diving in, ask the user:
+- What specific insights are they looking for?
+- Are there any known data quality issues?
+- What format do they want for the output?
+
+## 3. Perform Analysis
+Use pandas for data manipulation:
+
+import pandas as pd
+
+# Load and explore
+df = pd.read_csv("data.csv")
+print(df.head())
+print(df.describe())
+print(df.info())
+
+For visualization, prefer matplotlib or seaborn depending on complexity.
+```
+
+Skills transform Cline from a general-purpose assistant into a specialist that knows your domain. Start with one skill for a task you repeat often, test it, and iterate on the description until it triggers reliably.