Guide · Agent skill

How to use the Linear Channel Integration agent skill (add-linear)

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The add-linear skill connects NanoClaw, an agent host, to a Linear team so the agent can read and reply to comments on that team's issues. This guide explains what an agent skill is, how to install this one from the downloaded ZIP, how to trigger it, and what it needs before you start. By the end you will know which credentials to prepare, how the wiring works, and when this skill is the wrong choice.

Linear Channel Integrationnanocoai/nanoclaw · MIT Download the skill

Quick start

1Check prerequisites. Confirm you have a NanoClaw repository with a channels branch, pnpm, and a running NanoClaw host service.
2Create a Linear OAuth app. In Linear Settings > API > OAuth Applications, create an app, enable Client credentials, and copy the Client ID and Client Secret.
3Create a webhook. Add a webhook labelled NanoClaw at your public URL ending in /webhook/linear, select the team, check Comment, and copy the signing secret.
4Install the skill. Unzip the downloaded add-linear folder into ~/.claude/skills/ or your project's .claude/skills/, or upload the ZIP under Settings → Capabilities → Skills.
5Run the skill. Ask your agent to add the Linear channel and answer the prompts for credentials, team key and bot name.
6Wire the team to an agent. Pick the agent folder from ncl groups list and choose public or strict as the sender policy.
7Restart and test. Restart the NanoClaw service, then post a comment on a team issue to confirm the agent responds.

What is an agent skill and what does add-linear do?

An agent skill is a folder containing a SKILL.md file and supporting files that tell an AI agent how to perform a specific task. This skill lives at .claude/skills/add-linear in the nanocoai/nanoclaw repository and is licensed MIT.

Once applied, the skill adds a Linear connector to NanoClaw. Every new comment on the team's issues triggers the agent, so you do not need to @-mention it. Each issue thread becomes its own conversation.

Copies a Linear adapter from the channels branch of the repository into src/channels/
Adds one import line to src/channels/index.ts to register the adapter
Installs the @chat-adapter/linear npm package pinned to version 4.41.1
Runs a build and an integration test
Asks you for Linear credentials and a team key and writes them to a .env file

What you need before installing

The skill only applies inside the NanoClaw codebase. You need a NanoClaw repository with a channels branch, pnpm with build and vitest available, and a running NanoClaw host service, because ncl connects to it over a Unix socket.

You also need a Linear OAuth application (recommended) or a Personal API key, and a Linear webhook with a signing secret. The webhook must be reachable through a public URL or a tunnel. The skill uses the network and runs scripts.

Install the skill from the ZIP

Download the ZIP for add-linear from this page and unzip it. Place the resulting folder in ~/.claude/skills/ to make it available everywhere, or in your project's .claude/skills/ folder to limit it to one project.

Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Create the Linear OAuth app and webhook

Create a Linear OAuth application under Settings > API > OAuth Applications, enable Client credentials as a grant type, and copy the Client ID and Client Secret. The source recommends this route because the agent then posts as an app identity rather than as you, which stops the adapter from filtering your own comments as self-messages.

Then create a webhook under Settings > API > Webhooks with the label NanoClaw, a URL of the form https://your-domain/webhook/linear, your team selected, and the Comment event checked. Copy the signing secret. Linear may delay delivery for new webhooks by 1-5 minutes.

Developer URL: your repository URL
Callback URL: http://localhost
Personal API key option: sets LINEAR_API_KEY and the agent posts as you

Trigger the skill with a natural request

Ask your coding agent in plain language to add the Linear channel. The skill's SKILL.md describes the mechanical steps, so the agent reads the prose and applies them. Because every directive is idempotent, you can re-run the skill safely if a step was interrupted.

During the run you will be prompted for the OAuth Client ID, Client Secret, webhook signing secret, team key and bot display name. Enter none at the OAuth prompts if you use a Personal API key instead.

Example request: add the Linear channel to NanoClaw so the agent answers issue comments
Example request: set up Linear with a Personal API key for my team ENG
Example request: remove the Linear integration

Wire the team to an agent and choose a sender policy

Linear is team-routed. Choose which agent should answer, using the folder shown by ncl groups list. Then choose a sender policy: use public for a private workspace where only members can comment, and strict for a public workspace so only registered members may talk to the agent.

The wiring creates a messaging group for linear:TEAMKEY and a wiring with the pattern engage mode and session mode per-thread. There is no welcome message because Linear has no direct messages.

ncl groups list

Safety notes: scripts, network and credentials

This skill runs scripts and uses the network. It stores credentials in a local .env file and syncs them into the agent container. If you do not want that, do not use this skill.

Keep a public workspace on strict. Otherwise outside users can trigger the agent. The webhook server listens on 127.0.0.1 only by default. If your proxy or tunnel runs on another machine or in Docker on Linux, the source says to add WEBHOOK_HOST=0.0.0.0 to .env, which takes effect at the next restart.

Pinned dependency: the supply-chain policy rejects ranges and latest
Credentials are set only if absent, so existing values are not overwritten
To remove the skill, follow REMOVE.md: delete the import line and copied files, remove the LINEAR_ variables from .env, uninstall the package, then rebuild and restart

Tips for a smooth setup

Run the build and test steps before continuing; both must be clean. The test checks that the linear channel is registered and fails if the dependency is missing. End-to-end delivery against a real workspace is verified manually once the service is running.

After the skill finishes, restart the NanoClaw service so the new channel is picked up. The restart command differs between macOS and Linux, so use the one that matches your system.

If you are in the middle of /setup, return to the setup flow instead of restarting
Use the team key shown in Linear under Settings > Teams, for example ENG or NAN

source setup/lib/install-slug.sh
launchctl kickstart -k gui/$(id -u)/$(launchd_label)  # macOS
systemctl --user restart $(systemd_unit)              # Linux

What people use it for

A development team has the agent summarise or answer questions on comments in their Linear issues.
An admin of a private Linear workspace lets the agent reply to any member's comment on team issues.
A team using a Personal API key lets the agent post comments under their own name while keeping their own comments filtered out.

Frequently asked questions

How do I install the add-linear agent skill?

Download the add-linear ZIP from this page and unzip it into ~/.claude/skills/ for all projects or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What do I need to use add-linear?

You need a NanoClaw repository with a channels branch, pnpm with build and vitest, a running NanoClaw host service, a Linear OAuth app or Personal API key, and a Linear webhook with a signing secret reachable at a public URL or tunnel.

Is the add-linear skill free?

The skill is licensed under MIT, as stated for this item. The source does not mention pricing, so check the repository for any other terms.

Does the agent need an @-mention to reply in Linear?

No. Every new comment on the team's issues triggers the agent. The skill sets the engage pattern to respond to every comment, because Linear apps cannot be @-mentioned.

Why does the skill recommend an OAuth app instead of a Personal API key?

With an OAuth app the agent posts as an app identity, not as you. The source says this prevents the adapter from filtering your own comments as self-messages. A Personal API key posts as you and filters your own comments, though other team members' comments still work.

Why are my Linear comments not reaching the agent?

Check that the webhook URL ends in /webhook/linear and that the Comment event is checked. Allow 1-5 minutes for new webhooks, since the source says delivery may be delayed. If the tunnel runs on another machine or in Docker on Linux, add WEBHOOK_HOST=0.0.0.0 to .env and restart.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use add-linear if you already run NanoClaw, your team works in Linear, and you are comfortable creating an OAuth app and webhook. Pick a different option if you do not run NanoClaw, if your Linear workspace is public and you cannot enforce a strict sender policy, or if you do not want credentials stored in a local .env file.

Download the skill