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