commit 3fbe53f8c168a8a911d7e6dfaddd19169ea0a3aa Author: sloane Date: Tue Nov 4 15:28:14 2025 -0500 initial commit diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..75e8795 --- /dev/null +++ b/SKILL.md @@ -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.