agent-toolkit-cli 1.0.3__py3-none-any.whl

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/integrations/clickup-cli/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: clickup-cli
+description: ClickUp CLI for managing tasks, sprints, comments, statuses, and Docs. Use when the user needs to interact with ClickUp — creating/editing tasks, checking sprint status, adding comments, linking PRs, managing Docs and pages, or searching tasks. Prefer this CLI over raw API calls.
+---
+
+# ClickUp CLI (`clickup`)
+
+Use the `clickup` CLI instead of raw ClickUp API calls. Handles authentication, git integration,
+fuzzy status matching, and custom fields automatically.
+
+## When to use
+
+- Create, edit, view, or search ClickUp tasks
+- Check sprint status or recent tasks
+- Add comments, link PRs/branches, or manage statuses
+- Task IDs: `CU-abc123` or `86abc123`
+
+## Out of scope
+
+- Does NOT replace project management decisions — confirm scope with user first
+- Does NOT push code or create PRs — delegate to **`github-cli-workflow`**
+
+## Authentication
+
+```bash
+clickup auth login    # store API token
+clickup auth status   # verify
+```
+
+Config: `~/.config/clickup/config.yml`. Supports per-directory defaults.
+
+## Key rules
+
+1. **Always `--current`** for sprint lists — IDs change every sprint, never hardcode them
+2. **Fill ALL fields** when creating tasks (name, description, status, priority, assignee, tags, due-date)
+3. **Check `clickup tag list`** before using tags — reuse existing ones
+4. **Naming:** `[Work Type] Context — Action (Platform/Scope)` — see `references/task-management.md`
+5. **Bulk ops:** pass multiple IDs as positional args; for subtasks view parent with `--json` first
+
+## Quick commands
+
+```bash
+clickup task view                     # auto-detects from git branch
+clickup task search "query"
+clickup task recent --sprint
+clickup task create --current --name "[Bug] Auth — Fix X (API)" --priority 2
+clickup task edit CU-abc123 --status "in progress"
+clickup status list                   # check valid statuses before setting
+clickup sprint current
+clickup inbox
+```
+
+## Common flags
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output |
+| `--jq <expr>` | Filter with jq |
+| `--raw`, `-r` | Raw strings with `--jq` |
+
+## References
+
+- `references/task-management.md` — full task view/search/create/edit, naming conventions, multi-list, checklists, git integration
+- `references/time-tracking.md` — log, list, timesheet commands
+- `references/docs-management.md` — Docs and Pages management
+
+## Other commands
+
+```bash
+clickup member list
+clickup space list && clickup space select
+clickup folder list && clickup folder select
+clickup list list --folder 12345 && clickup list select
+clickup chat send <channel-id> "message"
+```

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/integrations/clickup-cli/references/docs-management.md

@@ -0,0 +1,57 @@
+# ClickUp CLI — Docs & Pages Reference
+
+> API limitation: Delete, archive, and restore for Docs/Pages are not available via the public v3 API.
+
+## Docs
+
+```bash
+clickup doc list
+clickup doc list --json
+clickup doc list --parent-id 123456 --parent-type SPACE
+clickup doc list --archived
+clickup doc view <doc-id>
+clickup doc view <doc-id> --json
+
+# Create
+clickup doc create --name "Project Runbook"
+clickup doc create --name "Team Wiki" \
+  --parent-id 123456 --parent-type SPACE --visibility PUBLIC
+clickup doc create --name "Drafts" --create-page=false
+```
+
+## Pages
+
+```bash
+clickup doc page list <doc-id>
+clickup doc page list <doc-id> --max-depth 0
+clickup doc page view <doc-id> <page-id>
+clickup doc page view <doc-id> <page-id> --content-format text/md
+
+# Create
+clickup doc page create <doc-id> --name "Introduction"
+clickup doc page create <doc-id> --name "Setup Guide" \
+  --content "# Setup\n\nFollow these steps..." --content-format text/md
+clickup doc page create <doc-id> --name "Advanced Config" \
+  --parent-page-id <parent-page-id>
+
+# Edit (replace / append / prepend)
+clickup doc page edit <doc-id> <page-id> --content "New content"
+clickup doc page edit <doc-id> <page-id> \
+  --content "## Release Notes\n\n- Fixed bug X" --content-edit-mode append
+clickup doc page edit <doc-id> <page-id> --name "Updated Title"
+```
+
+## JSON-first agent patterns
+
+```bash
+clickup doc list --jq '.[].id'
+clickup doc page list <doc-id> --jq '.pages[].id'
+
+# Append release notes
+clickup doc page edit <doc-id> <page-id> \
+  --content "## v1.2.3\n\n- Fixed auth timeout" \
+  --content-edit-mode append --content-format text/md
+
+# Capture new doc ID
+clickup doc create --name "Sprint Retro" --json | jq -r '.id'
+```

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/integrations/clickup-cli/references/task-management.md

@@ -0,0 +1,131 @@
+# ClickUp CLI — Task Management Reference
+
+## View & Search
+
+```bash
+clickup task view                          # auto-detects from git branch
+clickup task view CU-abc123
+clickup task view 86abc123 --json
+clickup task view 86abc1 86abc2 86abc3 --json        # bulk, up to 10 parallel
+clickup task view 86abc123 --recursive --json        # subtasks tree
+clickup task search "login bug"
+clickup task search "login bug" --exact
+clickup task search "login bug" --assignee me
+clickup task recent
+clickup task recent --sprint
+clickup task list --list-id 12345
+clickup task list                          # uses configured default list
+clickup task list --include-closed
+```
+
+**Navigating subtasks:** `--json` gives `subtasks[].id`, `start_date`, `due_date` inline.
+
+## Task Naming Convention
+
+Format: `[Work Type] Context — Action (Platform/Scope)`
+
+| Component | Purpose | Examples |
+|-----------|---------|----------|
+| `[Work Type]` | Category | `[Bug]`, `[Feature]`, `[Refactor]`, `[Spike]`, `[Hotfix]`, `[Packdown]` |
+| `Context` | Campaign or feature | `NT x THL`, `Auth v2` |
+| `Action` | Imperative verb | `Fix timeout`, `Add SSO` |
+| `(Platform)` | App or system | `(CamperMate)`, `(API)` |
+
+Examples:
+
+- `[Bug] Booking Flow — Fix timeout on slow connections (API)`
+- `[Packdown] NT x THL — Remove CamperMate campaign landing page`
+- `[Feature] Auth v2 — Add SSO support (CamperMate)`
+
+Use `{Campaign}` placeholder for template tasks.
+
+## Create & Edit
+
+**Always fill ALL applicable fields. Always use `--current` not hardcoded sprint IDs.**
+
+```bash
+# Create with full details
+clickup task create --current \
+  --name "[Bug] Auth — Fix login timeout (API)" \
+  --markdown-description "Users on 3G get timeout..." \
+  --status "open" --priority 2 \
+  --assignee 12345678 --tags "bug" --tags "auth" \
+  --due-date 2026-03-01 --time-estimate 4h --points 3
+
+# Create by list name
+clickup task create --list-name "Sprint 89" --name "Fix bug" --status "open"
+
+# Bulk create from JSON
+clickup task create --current --from-file tasks.json
+```
+
+JSON format for `--from-file`:
+
+```json
+[
+  {
+    "name": "Design homepage",
+    "description": "Create wireframes",
+    "status": "open", "priority": 2,
+    "due_date": "2026-03-15", "time_estimate": "4h",
+    "tags": ["design"], "parent": "86abc123"
+  }
+]
+```
+
+```bash
+# Edit
+clickup task edit --status "in progress"
+clickup task edit CU-abc123 --field "Environment=production"
+clickup task edit --due-date 2026-03-01 --time-estimate 4h
+
+# Bulk edit
+clickup task edit 86abc1 86abc2 86abc3 --status "Closed"
+clickup task edit 86abc1 86abc2 --add-tags "r&d"
+clickup task edit CU-abc123 --remove-tags "fix"
+clickup task edit CU-abc123 --clear-field "Environment"
+
+# Tags — always check available first
+clickup tag list
+
+# Status management
+clickup status set "in progress"
+clickup status list
+clickup status add "QA Review" --color "#7C4DFF"
+
+# Delete
+clickup task delete 86abc1 86abc2 86abc3 -y
+```
+
+**Bulk subtask workflow:** view parent with `--json` → extract `.subtasks[].id` → pass to `task edit`.
+
+## Multi-List & Comments
+
+```bash
+clickup task list-add 86abc123 --list-id 901613544162
+clickup task list-remove 86abc123 --list-id 901613544162
+
+clickup comment add CU-abc123 "Looks good, @alice please review"
+clickup comment list CU-abc123
+clickup comment edit <comment-id> "Updated text"
+```
+
+## Git & GitHub Integration
+
+```bash
+clickup link pr                            # auto-detects branch
+clickup link pr --task CU-abc123
+clickup link pr 42 --task CU-abc123        # specific PR number
+clickup link branch
+clickup link commit
+clickup link sync
+```
+
+## Checklists
+
+```bash
+clickup task checklist add <task-id> "Acceptance Criteria"
+clickup task checklist item add <checklist-id> "Unit tests pass"
+clickup task checklist item add <checklist-id> "Assigned item" --assignee 12345678
+clickup task checklist item edit <checklist-id> <item-id> --assignee 12345678
+```

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/integrations/clickup-cli/references/time-tracking.md

@@ -0,0 +1,38 @@
+# ClickUp CLI — Time Tracking Reference
+
+```bash
+# Log time
+clickup task time log --duration 2h
+clickup task time log 86abc123 --duration 1h30m --description "Auth flow"
+clickup task time log --duration 45m --date 2026-01-15
+clickup task time log --duration 3h --billable
+clickup task time log 86abc123 --duration 2h --assignee 54874661
+
+# Bulk log from file
+clickup task time log --from-file entries.json
+```
+
+JSON format:
+
+```json
+[
+  {"task_id": "86abc123", "duration": "2h", "date": "2026-03-15",
+   "description": "Feature work", "assignee": "54874661"},
+  {"task_id": "86abc456", "duration": "1h30m", "date": "2026-03-15"}
+]
+```
+
+```bash
+# List time entries
+clickup task time list
+clickup task time list 86abc123 --json
+
+# Timesheet (date range → timesheet mode)
+clickup task time list --start-date 2026-02-01 --end-date 2026-02-28
+clickup task time list --start-date 2026-02-01 --end-date 2026-02-28 --assignee 54695018
+clickup task time list --start-date 2026-03-01 --end-date 2026-03-31 --assignee id1,id2,id3
+clickup task time list --start-date 2026-02-01 --end-date 2026-02-28 --assignee all
+
+# Include tags in output (for CapEx auditing)
+clickup task time list --start-date 2026-03-01 --end-date 2026-03-31 --include-tags --json
+```

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/integrations/linear/LICENSE.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/integrations/linear/NOTICE.txt

@@ -0,0 +1,23 @@
+linear (agent-toolkit distribution)
+=============================
+
+This skill is derived from the OpenAI "skills" repository, originally licensed
+under the Apache License 2.0:
+
+  https://github.com/openai/skills (skills/.curated/linear)
+
+Modifications by agent-toolkit S.A. for distribution via agent-toolkit:
+
+- Removed Codex-specific setup (`codex mcp add`, `codex mcp login`,
+  `[features].rmcp_client`, `--enable rmcp_client`, references to restarting
+  Codex).
+- Removed `metadata.short-description: "Manage Linear issues in Codex"` and
+  `agents/openai.yaml` in favor of the agent-toolkit `skill.json` schema.
+- Replaced the setup section with a tool-agnostic matrix (Claude Code, Cursor,
+  OpenCode, Windsurf) that points to the chezmoi-managed MCP template at
+  `~/.local/share/agent-toolkit/mcp/linear/`.
+- Added a Boundaries section forbidding direct Linear REST/GraphQL access in
+  favor of the auditable MCP path.
+- Dropped vendor logo assets (`assets/linear*`).
+
+Original LICENSE.txt is preserved in this directory.

agent_toolkit_cli-1.0.3.data/data/agent_toolkit/data/skills/integrations/linear/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: linear
+description: Manage Linear issues, projects and cycles via the Linear MCP server. Use when the user wants to read, triage, create or update Linear tickets, plan a sprint, audit Linear documentation, or rebalance team workload.
+---
+
+# Linear
+
+Structured workflow for managing Linear issues, projects and cycles through the
+official Linear MCP server (`https://mcp.linear.app/mcp`, OAuth).
+
+This skill assumes the MCP is wired into your AI tool. See
+[`docs/MCP_TEMPLATES.md`](../../../../../../docs/MCP_TEMPLATES.md) and
+`~/.local/share/agent-toolkit/mcp/linear/` for the managed template.
+
+## When to use
+
+- "Open a Linear ticket for X", "triage open bugs", "plan the next cycle".
+- Sprint/cycle planning, retrospectives, documentation audits.
+- Cross-project dependency review or workload rebalancing.
+- Any natural-language request that maps onto Linear's MCP toolset.
+
+## Prerequisites
+
+1. Linear MCP server connected via OAuth in your AI tool of choice.
+2. Workspace access to the relevant teams and projects.
+3. agent-toolkit template available at `~/.local/share/agent-toolkit/mcp/linear/`
+   (deployed by `chezmoi apply`).
+
+## Setup (per AI tool)
+
+The Linear MCP is a **streamable HTTP** endpoint with OAuth. Register it in
+your AI tool of choice using the agent-toolkit template as reference:
+
+| AI tool | Where to register |
+|---------|-------------------|
+| Claude Code | `~/.claude/mcp.json` (or via `claude mcp add`) |
+| Cursor | `~/.cursor/mcp.json` |
+| OpenCode | `~/.config/opencode/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
+Copy `~/.local/share/agent-toolkit/mcp/linear/config.template.json` into the right
+location and follow the OAuth prompt the first time you call a Linear tool.
+
+> Windows / WSL note: if direct connections fail on Windows, run the MCP through
+> WSL using `npx -y mcp-remote https://mcp.linear.app/sse --transport sse-only`
+> as the command. The template includes a comment block with this fallback.
+
+## Required workflow
+
+**Follow the steps in order. Do not skip read-before-write.**
+
+### Step 1 — Clarify scope
+
+Confirm with the user:
+
+- Team / project / cycle in scope.
+- Goal (triage, planning, audit, rebalance, release planning).
+- Filters that matter (priority, label, assignee, status).
+
+### Step 2 — Pick the workflow and tools
+
+Match the goal to a workflow (see "Practical workflows" below) and identify the
+Linear MCP tools you will call. Confirm required identifiers (`issueId`,
+`projectId`, `teamKey`) before invoking write actions.
+
+### Step 3 — Execute in logical batches
+
+1. **Read first** (`list_*`, `get_*`, `search_*`) to build context.
+2. **Then write** (`create_*`, `update_*`, `create_comment`) with all required fields.
+3. **For bulk operations**, explain the grouping logic before applying changes.
+
+### Step 4 — Summarize and propose next actions
+
+Surface remaining gaps, blockers, and follow-ups (extra issues, label changes,
+re-assignments, follow-up comments).
+
+## Available MCP tools
+
+- **Issues**: `list_issues`, `get_issue`, `create_issue`, `update_issue`,
+  `list_my_issues`, `list_issue_statuses`, `list_issue_labels`,
+  `create_issue_label`
+- **Projects & teams**: `list_projects`, `get_project`, `create_project`,
+  `update_project`, `list_teams`, `get_team`, `list_users`
+- **Docs & collaboration**: `list_documents`, `get_document`,
+  `search_documentation`, `list_comments`, `create_comment`, `list_cycles`
+
+## Practical workflows
+
+- **Sprint planning** — review open issues for a team, pick top items by
+  priority, create a new cycle with assignments.
+- **Bug triage** — list critical/high bugs, rank by user impact, move top items
+  to In Progress.
+- **Documentation audit** — search docs (e.g. API auth), open labeled
+  `documentation` issues for gaps with detailed fixes.
+- **Workload balance** — group active issues by assignee, flag overloads,
+  propose redistributions.
+- **Release planning** — create a project (e.g. `v2.0 Release`) with milestones
+  (feature freeze, beta, docs, launch) and generate issues with estimates.
+- **Cross-project dependencies** — find all `blocked` issues, identify blockers,
+  create linked issues if missing.
+- **Status sweeps** — find your stale issues and add status comments based on
+  current state/blockers.
+- **Smart labeling** — analyze unlabeled issues, suggest/apply labels, create
+  missing label categories.
+- **Retrospectives** — report on the last completed cycle (completed vs pushed)
+  and open discussion issues for recurring patterns.
+
+## Boundaries
+
+- All access is via the Linear MCP. **Do not** call the Linear REST/GraphQL API
+  directly from this skill — that bypasses the auditable OAuth path.
+- No bulk destructive actions without an explicit confirmation step from the user.
+- Respect Linear API rate limits — batch reads, paginate, cache filters.
+
+## Troubleshooting
+
+- **Auth**: clear browser cookies, re-run OAuth, verify workspace permissions
+  and that API access is enabled for your account.
+- **Tool errors**: confirm your AI tool supports parallel tool calls; supply all
+  required fields; split complex requests into smaller calls.
+- **Missing data**: refresh the OAuth token, verify workspace access, check for
+  archived projects, confirm correct team selection.
+- **Performance**: respect rate limits — batch bulk ops, use specific filters,
+  cache frequent queries.
+
+## Validation
+
+- `doctor` lists the Linear MCP template under `mcp/linear/` once
+  `chezmoi apply` has run.
+- The first MCP tool call triggers the OAuth flow; from then on the AI tool
+  caches the session.