initial commit
This commit is contained in:
commit
3fbe53f8c1
1 changed files with 238 additions and 0 deletions
238
SKILL.md
Normal file
238
SKILL.md
Normal file
|
|
@ -0,0 +1,238 @@
|
||||||
|
---
|
||||||
|
name: linear
|
||||||
|
description: Expert guidance for Linear issue management and workflows using linear-cli - streamline issue tracking, project planning, and team collaboration from the command line
|
||||||
|
tags: [linear, issue-tracking, project-management, workflow, productivity]
|
||||||
|
version: 1.0.0
|
||||||
|
---
|
||||||
|
|
||||||
|
# Linear CLI Skill
|
||||||
|
|
||||||
|
Expert assistance for managing Linear issues, projects, and teams using the linear-cli tool. This skill helps you work efficiently with Linear's issue tracking platform directly from your terminal, with built-in awareness of Git and Jujutsu version control workflows.
|
||||||
|
|
||||||
|
## What is Linear?
|
||||||
|
|
||||||
|
Linear is a purpose-built software development platform for modern product teams. It provides:
|
||||||
|
- **Issue & Task Tracking**: Optimized for fast, focused work
|
||||||
|
- **Project Planning**: Visual timelines, milestones, and specifications
|
||||||
|
- **Sprint Management**: Cycles for building healthy team routines
|
||||||
|
- **Triage**: Manage incoming bugs and feature requests
|
||||||
|
- **Analytics**: Real-time insights and reporting
|
||||||
|
- **Integrations**: 100+ external tools including Git, Figma, and AI assistants
|
||||||
|
|
||||||
|
## What is linear-cli?
|
||||||
|
|
||||||
|
linear-cli is a command-line tool that bridges Linear issue tracking with development workflows. It's VCS-aware (works with both Git and Jujutsu) to keep you in the right views in Linear based on your current branch or commit.
|
||||||
|
|
||||||
|
**Key Benefits:**
|
||||||
|
- Manage issues without leaving the terminal
|
||||||
|
- Automatic issue detection from Git branches (e.g., `eng-123-my-feature`)
|
||||||
|
- Jujutsu integration via `Linear-issue` trailers in commit descriptions
|
||||||
|
- Create pull requests with auto-populated issue details
|
||||||
|
- Quick navigation to issues in browser, desktop app, or terminal
|
||||||
|
|
||||||
|
## Core Capabilities
|
||||||
|
|
||||||
|
### Issue Management
|
||||||
|
|
||||||
|
**View and Navigate Issues:**
|
||||||
|
```bash
|
||||||
|
# View issue details (auto-detects from current branch/commit)
|
||||||
|
linear issue view
|
||||||
|
linear issue view ENG-123
|
||||||
|
|
||||||
|
# Open issue in browser or Linear app
|
||||||
|
linear issue view --web
|
||||||
|
linear issue view --app
|
||||||
|
|
||||||
|
# Get issue information
|
||||||
|
linear issue id # Print issue ID from current branch
|
||||||
|
linear issue title # Print issue title
|
||||||
|
linear issue url # Print issue URL
|
||||||
|
linear issue describe # Print title and Linear-issue trailer
|
||||||
|
```
|
||||||
|
|
||||||
|
**List and Search:**
|
||||||
|
```bash
|
||||||
|
# List your issues
|
||||||
|
linear issue list
|
||||||
|
|
||||||
|
# Filter and search options available via the list command
|
||||||
|
```
|
||||||
|
|
||||||
|
**Create and Update:**
|
||||||
|
```bash
|
||||||
|
# Create a new issue (interactive)
|
||||||
|
linear issue create
|
||||||
|
|
||||||
|
# Update an issue
|
||||||
|
linear issue update # Updates current issue
|
||||||
|
linear issue update ENG-123 # Updates specific issue
|
||||||
|
|
||||||
|
# Delete an issue
|
||||||
|
linear issue delete ENG-123
|
||||||
|
```
|
||||||
|
|
||||||
|
**Workflow Actions:**
|
||||||
|
```bash
|
||||||
|
# Start working on an issue
|
||||||
|
linear issue start # Start current issue
|
||||||
|
linear issue start ENG-123 # Start specific issue
|
||||||
|
|
||||||
|
# Create GitHub PR with Linear issue details
|
||||||
|
linear issue pr # For current issue
|
||||||
|
linear issue pr ENG-123 # For specific issue
|
||||||
|
```
|
||||||
|
|
||||||
|
### Team Management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List teams
|
||||||
|
linear team list
|
||||||
|
|
||||||
|
# Get configured team ID
|
||||||
|
linear team id
|
||||||
|
|
||||||
|
# List team members
|
||||||
|
linear team members # Current team
|
||||||
|
linear team members ENG # Specific team
|
||||||
|
|
||||||
|
# Create a team
|
||||||
|
linear team create
|
||||||
|
|
||||||
|
# Configure GitHub repository autolinks
|
||||||
|
linear team autolinks
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List projects
|
||||||
|
linear project list
|
||||||
|
|
||||||
|
# View project details
|
||||||
|
linear project view PROJECT-123
|
||||||
|
linear project v PROJECT-123 # Shorthand
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Initial setup (creates .linear.toml)
|
||||||
|
linear config
|
||||||
|
|
||||||
|
# Generate shell completions
|
||||||
|
linear completions
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration Setup
|
||||||
|
|
||||||
|
First-time setup requires:
|
||||||
|
1. Linear API key (get from Linear settings)
|
||||||
|
2. Workspace selection
|
||||||
|
3. Default team selection
|
||||||
|
|
||||||
|
The tool creates a `.linear.toml` file with these settings.
|
||||||
|
|
||||||
|
## Version Control Integration
|
||||||
|
|
||||||
|
### Git Integration
|
||||||
|
- Automatically detects issue IDs from branch names
|
||||||
|
- Common patterns: `eng-123-feature-name`, `ENG-123-bug-fix`
|
||||||
|
- Commands like `linear issue view` auto-detect the current issue
|
||||||
|
|
||||||
|
### Jujutsu (jj) Integration
|
||||||
|
- Reads `Linear-issue` trailers from commit descriptions
|
||||||
|
- Use `linear issue describe` to generate proper trailer format
|
||||||
|
- Seamless workflow with jj's change-centric model
|
||||||
|
|
||||||
|
## Common Workflows
|
||||||
|
|
||||||
|
### Starting Work on an Issue
|
||||||
|
```bash
|
||||||
|
# 1. List available issues
|
||||||
|
linear issue list
|
||||||
|
|
||||||
|
# 2. Start working on an issue (updates status)
|
||||||
|
linear issue start ENG-123
|
||||||
|
|
||||||
|
# 3. Create branch (if using Git)
|
||||||
|
git checkout -b eng-123-feature-name
|
||||||
|
|
||||||
|
# 4. Or with jj, add trailer to description
|
||||||
|
jj describe -m "Implement feature\n\nLinear-issue: ENG-123"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Creating a Pull Request
|
||||||
|
```bash
|
||||||
|
# Auto-populate PR with Linear issue details
|
||||||
|
linear issue pr
|
||||||
|
|
||||||
|
# This creates a GitHub PR with:
|
||||||
|
# - Issue title in PR title
|
||||||
|
# - Issue description in PR body
|
||||||
|
# - Automatic linking back to Linear
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quick Issue Lookup
|
||||||
|
```bash
|
||||||
|
# From any branch, quickly check what you're working on
|
||||||
|
linear issue title
|
||||||
|
linear issue url --web # Open in browser
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tips and Best Practices
|
||||||
|
|
||||||
|
1. **Branch Naming**: Use consistent patterns like `team-key-123-description` for automatic issue detection
|
||||||
|
2. **Configuration**: Run `linear config` in each project directory for project-specific settings
|
||||||
|
3. **Shell Completions**: Install completions for faster command entry
|
||||||
|
4. **Issue IDs**: Most commands accept optional `issueId` - omit it to use current branch/commit
|
||||||
|
5. **PR Integration**: Use `linear issue pr` to maintain Linear ↔ GitHub linkage
|
||||||
|
6. **Quick Access**: Alias common commands (e.g., `alias li='linear issue'`)
|
||||||
|
|
||||||
|
## Command Reference
|
||||||
|
|
||||||
|
| Command | Alias | Description |
|
||||||
|
|---------|-------|-------------|
|
||||||
|
| `linear issue` | `linear i` | Manage issues |
|
||||||
|
| `linear team` | `linear t` | Manage teams |
|
||||||
|
| `linear project` | `linear p` | Manage projects |
|
||||||
|
| `linear issue view` | `linear i v` | View issue details |
|
||||||
|
| `linear issue pull-request` | `linear i pr` | Create GitHub PR |
|
||||||
|
| `linear issue delete` | `linear i d` | Delete issue |
|
||||||
|
|
||||||
|
## Help and Documentation
|
||||||
|
|
||||||
|
- `linear --help`: Main help
|
||||||
|
- `linear issue --help`: Issue command help
|
||||||
|
- `linear team --help`: Team command help
|
||||||
|
- `linear project --help`: Project command help
|
||||||
|
- Repository: https://github.com/schpet/linear-cli
|
||||||
|
- Linear Platform: https://linear.app/
|
||||||
|
|
||||||
|
## Common Issues and Solutions
|
||||||
|
|
||||||
|
**Issue ID Not Detected:**
|
||||||
|
- Check branch name format matches expected patterns
|
||||||
|
- Use explicit issue ID: `linear issue view ENG-123`
|
||||||
|
- For jj, ensure `Linear-issue` trailer is in description
|
||||||
|
|
||||||
|
**Configuration Not Found:**
|
||||||
|
- Run `linear config` in project directory
|
||||||
|
- Verify `.linear.toml` exists and has correct API key
|
||||||
|
|
||||||
|
**Permission Errors:**
|
||||||
|
- Check Linear API key has correct permissions
|
||||||
|
- Verify team/workspace access
|
||||||
|
|
||||||
|
## Assistant Guidelines
|
||||||
|
|
||||||
|
When helping users with Linear CLI:
|
||||||
|
|
||||||
|
1. **Context Awareness**: Check if they're using Git or Jujutsu and provide appropriate guidance
|
||||||
|
2. **Issue Detection**: Remind users that many commands auto-detect issues from current branch/commit
|
||||||
|
3. **Workflow Integration**: Suggest ways to integrate Linear CLI into their development workflow
|
||||||
|
4. **Configuration First**: If errors occur, verify `linear config` has been run
|
||||||
|
5. **Shell Integration**: Recommend completions and aliases for power users
|
||||||
|
6. **Best Practices**: Encourage consistent branch naming and proper issue linking
|
||||||
|
|
||||||
|
Always use the actual linear-cli commands available on the system rather than making assumptions about functionality.
|
||||||
Loading…
Reference in a new issue