Initial commit
This commit is contained in:
Zhongwei Li
190
skills/jira-cli/SKILL.md
Normal file
190
skills/jira-cli/SKILL.md
Normal file
@@ -0,0 +1,190 @@
|
||||
---
|
||||
name: jira-cli
|
||||
description: Interactive command-line tool for Atlassian Jira. This skill should be used when users want to interact with Jira issues, epics, sprints, or when they mention Jira workflows, issue management, or need help with jira-cli commands and workflows.
|
||||
---
|
||||
|
||||
# Jira CLI
|
||||
|
||||
Interactive command-line tool for Atlassian Jira that minimizes reliance on the web interface while maintaining essential functionality for daily Jira operations.
|
||||
|
||||
## Overview
|
||||
|
||||
JiraCLI (`jira-cli`) is a command line tool for managing Jira issues, epics, and sprints. Supports both Jira Cloud and on-premise installations with multiple authentication methods.
|
||||
|
||||
**For AI use, always add `--plain` flag to get plain text output suitable for parsing.**
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Managing Jira issues from the command line
|
||||
- Creating, editing, or viewing Jira tickets
|
||||
- Working with epics and sprints
|
||||
- Automating Jira workflows
|
||||
- Users mention "jira", "ticket", "issue", "epic", or "sprint"
|
||||
- Writing scripts for Jira automation
|
||||
|
||||
## Essential Commands
|
||||
|
||||
```bash
|
||||
# List recent issues (always use --plain for AI)
|
||||
jira issue list --plain
|
||||
|
||||
# View issue details
|
||||
jira issue view ISSUE-1 --plain
|
||||
|
||||
# Create an issue
|
||||
jira issue create -tBug -s"Bug title" -yHigh -b"Description"
|
||||
|
||||
# Assign issue to yourself
|
||||
jira issue assign ISSUE-1 $(jira me)
|
||||
|
||||
# Move issue to "In Progress"
|
||||
jira issue move ISSUE-1 "In Progress"
|
||||
|
||||
# Add comment
|
||||
jira issue comment add ISSUE-1 --comment "My comment"
|
||||
|
||||
# Add worklog
|
||||
jira issue worklog add ISSUE-1 "2h" --comment "Implementation work"
|
||||
```
|
||||
|
||||
## How to Use This Skill
|
||||
|
||||
**For detailed command reference and examples, load the appropriate reference file:**
|
||||
|
||||
### 1. Comprehensive Commands Reference
|
||||
|
||||
**Load:** [references/commands.md](./references/commands.md)
|
||||
|
||||
Use this file when you need:
|
||||
- Detailed command syntax and options
|
||||
- All available flags and parameters
|
||||
- Issue management operations (list, create, edit, assign, move, view, link, clone, delete)
|
||||
- Epic management (list, create, add/remove issues)
|
||||
- Sprint management (list, add issues)
|
||||
- Release management
|
||||
- Output format options
|
||||
- Non-interactive command patterns
|
||||
|
||||
### 2. Common Workflow Examples
|
||||
|
||||
**Load:** [references/workflows.md](./references/workflows.md)
|
||||
|
||||
Use this file when you need:
|
||||
- Daily standup preparation workflows
|
||||
- Sprint planning commands
|
||||
- Code review workflow integration
|
||||
- Bug triage procedures
|
||||
- Team collaboration patterns
|
||||
- Best practices for different scenarios
|
||||
|
||||
### 3. Scripting and Automation
|
||||
|
||||
**Load:** [references/scripting.md](./references/scripting.md)
|
||||
|
||||
Use this file when you need:
|
||||
- Bash automation scripts
|
||||
- Data extraction and reporting
|
||||
- Integration with CI/CD pipelines
|
||||
- Metrics and analytics examples
|
||||
- Bulk operations
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Powerful List Filters
|
||||
|
||||
```bash
|
||||
# Combine flags for precise queries (always add --plain)
|
||||
jira issue list --plain -a$(jira me) -yHigh -s"To Do" --created -7d -lbackend
|
||||
|
||||
# Use tilde (~) as NOT operator
|
||||
jira issue list --plain -s~Done --created-before -24w
|
||||
|
||||
# Filter by multiple criteria
|
||||
jira issue list --plain -yHigh,Critical -s"In Progress" -lbug
|
||||
|
||||
# List issues I'm watching
|
||||
jira issue list --plain -w
|
||||
|
||||
# List issues assigned to no one created this week
|
||||
jira issue list --plain -ax --created week
|
||||
|
||||
# List issues created within an hour
|
||||
jira issue list --plain --created -1h
|
||||
|
||||
# List issues from history (recently viewed)
|
||||
jira issue list --plain --history
|
||||
```
|
||||
|
||||
### Sprint Management
|
||||
|
||||
```bash
|
||||
# List current active sprint issues
|
||||
jira sprint list --plain --current
|
||||
|
||||
# List current sprint issues assigned to me
|
||||
jira sprint list --plain --current -a$(jira me)
|
||||
|
||||
# List previous sprint issues
|
||||
jira sprint list --plain --prev
|
||||
|
||||
# List next planned sprint issues
|
||||
jira sprint list --plain --next
|
||||
|
||||
# List future and active sprints
|
||||
jira sprint list --plain --state future,active
|
||||
|
||||
# List issues in a specific sprint (use sprint ID)
|
||||
jira sprint list --plain SPRINT_ID
|
||||
|
||||
# Add issues to a sprint
|
||||
jira sprint add SPRINT_ID ISSUE-1 ISSUE-2
|
||||
```
|
||||
|
||||
### Epic Management
|
||||
|
||||
```bash
|
||||
# List epics in table view
|
||||
jira epic list --plain --table
|
||||
|
||||
# List issues in an epic
|
||||
jira epic list --plain KEY-1
|
||||
|
||||
# List unassigned high priority issues in an epic
|
||||
jira epic list --plain KEY-1 -ax -yHigh
|
||||
|
||||
# Add issues to an epic (up to 50 at once)
|
||||
jira epic add EPIC-KEY ISSUE-1 ISSUE-2
|
||||
|
||||
# Remove issues from an epic
|
||||
jira epic remove ISSUE-1 ISSUE-2
|
||||
```
|
||||
|
||||
### Useful Scripts
|
||||
|
||||
```bash
|
||||
# Get ticket count per sprint
|
||||
sprints=$(jira sprint list --table --plain --columns id,name --no-headers)
|
||||
echo "${sprints}" | while read -r id name; do
|
||||
count=$(jira sprint list "${id}" --plain --no-headers 2>/dev/null | wc -l)
|
||||
printf "%s: %d\n" "${name}" "${count}"
|
||||
done
|
||||
|
||||
# List tickets created today
|
||||
jira issue list --plain --created -1d
|
||||
|
||||
# List high priority bugs assigned to me
|
||||
jira issue list --plain -a$(jira me) -tBug -yHigh
|
||||
|
||||
# Get issues by date range
|
||||
jira issue list --plain --created week
|
||||
jira issue list --plain --created month
|
||||
jira issue list --plain --created -7d
|
||||
jira issue list --plain --updated -30m
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- **GitHub**: https://github.com/ankitpokhrel/jira-cli
|
||||
- **Installation Guide**: https://github.com/ankitpokhrel/jira-cli/wiki/Installation
|
||||
- **FAQs**: https://github.com/ankitpokhrel/jira-cli/discussions/categories/faqs
|
||||
464
skills/jira-cli/references/commands.md
Normal file
464
skills/jira-cli/references/commands.md
Normal file
@@ -0,0 +1,464 @@
|
||||
# Jira CLI - Comprehensive Command Reference
|
||||
|
||||
This file contains detailed command syntax, options, and examples for all jira-cli operations.
|
||||
|
||||
## Issue Management
|
||||
|
||||
### Listing Issues
|
||||
|
||||
Use powerful filters to find exactly what you need:
|
||||
|
||||
```bash
|
||||
# Basic listing
|
||||
jira issue list # Recent issues
|
||||
jira issue list "Feature Request" # Search by specific text
|
||||
jira issue list --created -7d # Last 7 days
|
||||
jira issue list -s"To Do" # Specific status
|
||||
jira issue list -yHigh # High priority
|
||||
|
||||
# Personal queries
|
||||
jira issue list -a$(jira me) # Assigned to me
|
||||
jira issue list -r$(jira me) # Reported by me
|
||||
jira issue list -w # Issues I'm watching
|
||||
|
||||
# Filtering by fields
|
||||
jira issue list -lbackend # With label
|
||||
jira issue list -CBackend # With component
|
||||
jira issue list -tBug # Bug type
|
||||
jira issue list -R"Won't do" # With resolution
|
||||
|
||||
# Combined filters (high priority, In Progress, created this month, with labels)
|
||||
jira issue list -yHigh -s"In Progress" --created month -lbackend -l"high-prio"
|
||||
|
||||
# Time-based queries
|
||||
jira issue list --created -1h # Created in last hour
|
||||
jira issue list --updated -30m # Updated in last 30 minutes
|
||||
jira issue list --created week # Created this week
|
||||
jira issue list --created month # Created this month
|
||||
jira issue list --created-before -24w # Created before 24 weeks ago
|
||||
|
||||
# Advanced queries
|
||||
jira issue list -a"User A" -r"User B" # Assigned to A, reported by B
|
||||
jira issue list -ax # Unassigned issues
|
||||
jira issue list -a~x # Assigned to anyone
|
||||
jira issue list -s~Done # Status NOT done (~ is NOT)
|
||||
jira issue list -s~Done --created-before -24w -a~x # Complex NOT query
|
||||
|
||||
# Special queries
|
||||
jira issue list --history # Recently viewed by you
|
||||
jira issue list -r$(jira me) --reverse # First issue you ever reported
|
||||
jira issue list -a$(jira me) -tBug -sDone -rFixed --reverse # First bug you fixed
|
||||
|
||||
# Project-specific
|
||||
jira issue list -pXYZ # In project XYZ
|
||||
jira issue list -w -pXYZ # Watching in project XYZ
|
||||
|
||||
# Sorting and ordering
|
||||
jira issue list --order-by rank --reverse # By rank (same as UI)
|
||||
jira issue list --order-by created # By creation date
|
||||
jira issue list --order-by updated # By update date
|
||||
|
||||
# Output formats
|
||||
jira issue list --plain # Plain text
|
||||
jira issue list --csv # CSV format
|
||||
jira issue list --raw # Raw JSON
|
||||
jira issue list --columns key,summary,status,assignee # Custom columns
|
||||
jira issue list --plain --no-headers # No headers (for parsing)
|
||||
|
||||
# Raw JQL
|
||||
jira issue list -q "summary ~ cli" # Execute JQL in project context
|
||||
```
|
||||
|
||||
### Creating Issues
|
||||
|
||||
```bash
|
||||
# Interactive mode
|
||||
jira issue create
|
||||
|
||||
# Non-interactive with all parameters
|
||||
jira issue create -tBug -s"Bug title" -yHigh -lbug -lurgent -b"Description" --no-input
|
||||
|
||||
# Create with specific fields
|
||||
jira issue create -tStory -s"Story title" -yMedium -lfeature
|
||||
jira issue create -tTask -s"Task" -a"John Doe" -CBackend
|
||||
jira issue create -tBug -s"Critical bug" -yHighest --fix-version v2.0
|
||||
|
||||
# Attach to epic during creation
|
||||
jira issue create -tStory -s"Story title" -PEPIC-42
|
||||
|
||||
# Using templates for description
|
||||
jira issue create --template /path/to/template.md
|
||||
jira issue create --template - # From stdin
|
||||
|
||||
# Pipe description from stdin
|
||||
echo "Description from pipeline" | jira issue create -s"Summary" -tTask
|
||||
|
||||
# With custom fields
|
||||
jira issue create --custom field1=value1 --custom field2=value2
|
||||
```
|
||||
|
||||
### Editing Issues
|
||||
|
||||
```bash
|
||||
# Interactive edit
|
||||
jira issue edit ISSUE-1
|
||||
|
||||
# Update specific fields
|
||||
jira issue edit ISSUE-1 -s"New summary"
|
||||
jira issue edit ISSUE-1 -yHigh
|
||||
jira issue edit ISSUE-1 -b"New description"
|
||||
|
||||
# Update multiple fields at once
|
||||
jira issue edit ISSUE-1 -s"New summary" -yHigh -lurgent --no-input
|
||||
|
||||
# Add and remove labels/components
|
||||
jira issue edit ISSUE-1 --label new-label
|
||||
jira issue edit ISSUE-1 --label -old-label --label new-label
|
||||
jira issue edit ISSUE-1 --component -FE --component BE
|
||||
|
||||
# Update fix version
|
||||
jira issue edit ISSUE-1 --fix-version v2.0
|
||||
jira issue edit ISSUE-1 --fix-version -v1.0 --fix-version v2.0
|
||||
```
|
||||
|
||||
### Assigning Issues
|
||||
|
||||
```bash
|
||||
# Interactive assign
|
||||
jira issue assign
|
||||
|
||||
# Assign to specific user
|
||||
jira issue assign ISSUE-1 "Jon Doe"
|
||||
|
||||
# Assign to self
|
||||
jira issue assign ISSUE-1 $(jira me)
|
||||
|
||||
# Assign based on keyword (prompts if multiple matches)
|
||||
jira issue assign ISSUE-1 john
|
||||
|
||||
# Assign to default assignee
|
||||
jira issue assign ISSUE-1 default
|
||||
|
||||
# Unassign
|
||||
jira issue assign ISSUE-1 x
|
||||
```
|
||||
|
||||
### Moving/Transitioning Issues
|
||||
|
||||
```bash
|
||||
# Interactive transition
|
||||
jira issue move
|
||||
|
||||
# Move to specific status
|
||||
jira issue move ISSUE-1 "In Progress"
|
||||
jira issue move ISSUE-1 Done
|
||||
|
||||
# Move with comment
|
||||
jira issue move ISSUE-1 "In Progress" --comment "Started working on it"
|
||||
|
||||
# Set resolution and assignee while moving
|
||||
jira issue move ISSUE-1 Done -RFixed
|
||||
jira issue move ISSUE-1 Done -RFixed -a$(jira me)
|
||||
```
|
||||
|
||||
### Viewing Issues
|
||||
|
||||
```bash
|
||||
# View issue in terminal
|
||||
jira issue view ISSUE-1
|
||||
|
||||
# View with recent comments
|
||||
jira issue view ISSUE-1 --comments 5
|
||||
jira issue view ISSUE-1 --comments 10
|
||||
```
|
||||
|
||||
### Linking Issues
|
||||
|
||||
```bash
|
||||
# Interactive linking
|
||||
jira issue link
|
||||
|
||||
# Link with relationship type
|
||||
jira issue link ISSUE-1 ISSUE-2 Blocks
|
||||
jira issue link ISSUE-1 ISSUE-2 "is blocked by"
|
||||
jira issue link ISSUE-1 ISSUE-2 Duplicates
|
||||
jira issue link ISSUE-1 ISSUE-2 Relates
|
||||
|
||||
# Add remote web link
|
||||
jira issue link remote ISSUE-1 https://example.com "Example text"
|
||||
jira issue link remote ISSUE-1 https://github.com/org/repo/pull/123 "PR #123"
|
||||
|
||||
# Unlink issues
|
||||
jira issue unlink ISSUE-1 ISSUE-2
|
||||
```
|
||||
|
||||
### Cloning Issues
|
||||
|
||||
```bash
|
||||
# Clone an issue
|
||||
jira issue clone ISSUE-1
|
||||
|
||||
# Clone with modifications
|
||||
jira issue clone ISSUE-1 -s"Modified summary"
|
||||
jira issue clone ISSUE-1 -s"New title" -yHigh -a$(jira me)
|
||||
|
||||
# Clone and replace text in summary/description
|
||||
jira issue clone ISSUE-1 -H"old text:new text"
|
||||
jira issue clone ISSUE-1 -H"2024:2025"
|
||||
```
|
||||
|
||||
### Deleting Issues
|
||||
|
||||
```bash
|
||||
# Interactive delete
|
||||
jira issue delete
|
||||
|
||||
# Delete specific issue
|
||||
jira issue delete ISSUE-1
|
||||
|
||||
# Delete with all subtasks
|
||||
jira issue delete ISSUE-1 --cascade
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
```bash
|
||||
# Add comment interactively
|
||||
jira issue comment add
|
||||
|
||||
# Add comment with text
|
||||
jira issue comment add ISSUE-1 "My comment text"
|
||||
|
||||
# Add internal comment (visible only to team)
|
||||
jira issue comment add ISSUE-1 "Internal note" --internal
|
||||
|
||||
# Add comment from template
|
||||
jira issue comment add ISSUE-1 --template /path/to/comment.md
|
||||
jira issue comment add ISSUE-1 --template -
|
||||
|
||||
# Pipe comment from stdin
|
||||
echo "Comment from pipeline" | jira issue comment add ISSUE-1
|
||||
```
|
||||
|
||||
### Worklog (Time Tracking)
|
||||
|
||||
```bash
|
||||
# Add worklog interactively
|
||||
jira issue worklog add
|
||||
|
||||
# Add worklog with time
|
||||
jira issue worklog add ISSUE-1 "2h 30m" --no-input
|
||||
jira issue worklog add ISSUE-1 "1d" --no-input
|
||||
jira issue worklog add ISSUE-1 "30m" --no-input
|
||||
|
||||
# Add worklog with comment
|
||||
jira issue worklog add ISSUE-1 "2h" --comment "Implementation work" --no-input
|
||||
jira issue worklog add ISSUE-1 "1h 15m" --comment "Code review" --no-input
|
||||
```
|
||||
|
||||
## Epic Management
|
||||
|
||||
### Listing Epics
|
||||
|
||||
```bash
|
||||
# List all epics (explorer view)
|
||||
jira epic list
|
||||
|
||||
# List epics (table view)
|
||||
jira epic list --table
|
||||
|
||||
# List epics with filters (same filters as issue list)
|
||||
jira epic list -r$(jira me) # Reported by me
|
||||
jira epic list -sOpen # Open epics
|
||||
jira epic list -yHigh # High priority
|
||||
jira epic list -r$(jira me) -sOpen -yHigh # Combined filters
|
||||
|
||||
# List issues in an epic
|
||||
jira epic list EPIC-1
|
||||
|
||||
# List epic issues with filters
|
||||
jira epic list EPIC-1 -ax # Unassigned issues in epic
|
||||
jira epic list EPIC-1 -yHigh # High priority issues in epic
|
||||
jira epic list EPIC-1 -a$(jira me) # My issues in epic
|
||||
|
||||
# Order epic issues by rank
|
||||
jira epic list EPIC-1 --order-by rank --reverse
|
||||
```
|
||||
|
||||
### Creating Epics
|
||||
|
||||
```bash
|
||||
# Interactive
|
||||
jira epic create
|
||||
|
||||
# With parameters
|
||||
jira epic create -n"Epic name" -s"Epic summary"
|
||||
jira epic create -n"Q1 Features" -s"Q1 Feature Development" -yHigh -lfeature -b"Epic description"
|
||||
```
|
||||
|
||||
### Managing Epic Issues
|
||||
|
||||
```bash
|
||||
# Add issues to epic (interactive)
|
||||
jira epic add
|
||||
|
||||
# Add issues to epic (up to 50 at once)
|
||||
jira epic add EPIC-1 ISSUE-1 ISSUE-2 ISSUE-3
|
||||
|
||||
# Remove issues from epic (interactive)
|
||||
jira epic remove
|
||||
|
||||
# Remove issues from epic (up to 50 at once)
|
||||
jira epic remove ISSUE-1 ISSUE-2 ISSUE-3
|
||||
```
|
||||
|
||||
## Sprint Management
|
||||
|
||||
### Listing Sprints
|
||||
|
||||
```bash
|
||||
# List all sprints (explorer view)
|
||||
jira sprint list
|
||||
|
||||
# List sprints (table view)
|
||||
jira sprint list --table
|
||||
|
||||
# Current active sprint
|
||||
jira sprint list --current
|
||||
|
||||
# Current sprint with filters
|
||||
jira sprint list --current -a$(jira me)
|
||||
jira sprint list --current -yHigh
|
||||
jira sprint list --current -a$(jira me) -yHigh -s"In Progress"
|
||||
|
||||
# Previous sprint
|
||||
jira sprint list --prev
|
||||
|
||||
# Next planned sprint
|
||||
jira sprint list --next
|
||||
|
||||
# Filter by sprint state
|
||||
jira sprint list --state active
|
||||
jira sprint list --state future
|
||||
jira sprint list --state future,active
|
||||
jira sprint list --state closed
|
||||
|
||||
# Specific sprint (use ID from sprint list)
|
||||
jira sprint list SPRINT_ID
|
||||
jira sprint list SPRINT_ID -yHigh
|
||||
jira sprint list SPRINT_ID -a$(jira me)
|
||||
jira sprint list SPRINT_ID -yHigh -a$(jira me) -s"In Progress"
|
||||
|
||||
# Order sprint issues by rank
|
||||
jira sprint list SPRINT_ID --order-by rank --reverse
|
||||
```
|
||||
|
||||
### Adding Issues to Sprint
|
||||
|
||||
```bash
|
||||
# Add issues interactively
|
||||
jira sprint add
|
||||
|
||||
# Add multiple issues (up to 50 at once)
|
||||
jira sprint add SPRINT_ID ISSUE-1 ISSUE-2 ISSUE-3
|
||||
```
|
||||
|
||||
## Release Management
|
||||
|
||||
Interact with releases (project versions). Ensure the [feature is enabled](https://support.atlassian.com/jira-software-cloud/docs/enable-releases-and-versions/) on your instance.
|
||||
|
||||
```bash
|
||||
# List releases for default project
|
||||
jira release list
|
||||
|
||||
# List releases for specific project by ID
|
||||
jira release list --project 1000
|
||||
|
||||
# List releases for specific project by key
|
||||
jira release list --project MYPROJ
|
||||
```
|
||||
|
||||
## Other Commands
|
||||
|
||||
### Project and Board Navigation
|
||||
|
||||
```bash
|
||||
# Open project in browser
|
||||
jira open
|
||||
|
||||
# Open specific issue in browser
|
||||
jira open ISSUE-1
|
||||
|
||||
# List all projects you have access to
|
||||
jira project list
|
||||
|
||||
# List all boards in a project
|
||||
jira board list
|
||||
```
|
||||
|
||||
### User Information
|
||||
|
||||
```bash
|
||||
# Get your own username (useful in scripts)
|
||||
jira me
|
||||
```
|
||||
|
||||
## Navigation and Interaction
|
||||
|
||||
When in interactive UI:
|
||||
|
||||
**Movement:**
|
||||
- **Arrow keys** or **j,k,h,l** - Navigate through list
|
||||
- **g** - Jump to top
|
||||
- **G** - Jump to bottom
|
||||
- **CTRL+f** - Scroll page down
|
||||
- **CTRL+b** - Scroll page up
|
||||
|
||||
**Actions:**
|
||||
- **v** - View selected issue details
|
||||
- **m** - Transition the selected issue
|
||||
- **CTRL+r** or **F5** - Refresh the list
|
||||
- **ENTER** - Open selected issue in browser
|
||||
- **c** - Copy issue URL to clipboard (requires xclip/xsel on Linux)
|
||||
- **CTRL+k** - Copy issue key to clipboard
|
||||
- **w** or **TAB** - Toggle focus between sidebar and content
|
||||
- **q** / **ESC** / **CTRL+c** - Quit
|
||||
- **?** - Show help window
|
||||
|
||||
## Output Formats and Options
|
||||
|
||||
### Format Options
|
||||
|
||||
```bash
|
||||
# Interactive table (default)
|
||||
jira issue list
|
||||
|
||||
# Plain text output (for scripts)
|
||||
jira issue list --plain
|
||||
|
||||
# CSV format (for spreadsheets)
|
||||
jira issue list --csv
|
||||
|
||||
# Raw JSON (for programmatic parsing)
|
||||
jira issue list --raw
|
||||
```
|
||||
|
||||
### Column Selection
|
||||
|
||||
```bash
|
||||
# Default columns
|
||||
jira issue list
|
||||
|
||||
# Custom columns
|
||||
jira issue list --columns key,summary,status
|
||||
jira issue list --columns key,summary,status,assignee,priority
|
||||
jira issue list --columns created,updated,reporter
|
||||
|
||||
# Without headers (for parsing)
|
||||
jira issue list --plain --no-headers
|
||||
jira issue list --csv --no-headers
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
jira-cli handles pagination automatically. For very large result sets, the tool will fetch additional pages as needed.
|
||||
457
skills/jira-cli/references/scripting.md
Normal file
457
skills/jira-cli/references/scripting.md
Normal file
@@ -0,0 +1,457 @@
|
||||
# Jira CLI - Scripting and Automation
|
||||
|
||||
This file contains examples for automating Jira operations with scripts and integrating with CI/CD pipelines.
|
||||
|
||||
## Bash Scripting Examples
|
||||
|
||||
### Tickets Created Per Day This Month
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Generate report of tickets created per day in current month
|
||||
|
||||
tickets=$(jira issue list --created month --plain --columns created --no-headers | \
|
||||
awk '{print $2}' | awk -F'-' '{print $3}' | sort -n | uniq -c)
|
||||
|
||||
echo "${tickets}" | while IFS=$'\t' read -r line; do
|
||||
day=$(echo "${line}" | awk '{print $2}')
|
||||
count=$(echo "${line}" | awk '{print $1}')
|
||||
printf "Day #%s: %s tickets\n" "${day}" "${count}"
|
||||
done
|
||||
```
|
||||
|
||||
### Number of Tickets Per Sprint
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Count tickets in each sprint
|
||||
|
||||
sprints=$(jira sprint list --table --plain --columns id,name --no-headers)
|
||||
|
||||
echo "${sprints}" | while IFS=$'\t' read -r id name; do
|
||||
count=$(jira sprint list "${id}" --plain --no-headers 2>/dev/null | wc -l)
|
||||
printf "%10s: %3d tickets\n" "${name}" $((count))
|
||||
done
|
||||
```
|
||||
|
||||
### Number of Unique Assignees Per Sprint
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Count unique assignees in each sprint
|
||||
|
||||
sprints=$(jira sprint list --table --plain --columns id,name --no-headers)
|
||||
|
||||
echo "${sprints}" | while IFS=$'\t' read -r id name; do
|
||||
count=$(jira sprint list "${id}" --plain --columns assignee --no-headers 2>/dev/null | \
|
||||
awk '{print $2}' | awk NF | sort -n | uniq | wc -l)
|
||||
printf "%10s: %3d people\n" "${name}" $((count))
|
||||
done
|
||||
```
|
||||
|
||||
### Daily Standup Report
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Generate daily standup report
|
||||
|
||||
echo "=== Daily Standup Report ==="
|
||||
echo ""
|
||||
|
||||
echo "Yesterday's work (updated in last 24h):"
|
||||
jira issue list -a$(jira me) --updated -1d --plain --columns key,summary
|
||||
|
||||
echo ""
|
||||
echo "Currently working on:"
|
||||
jira issue list -a$(jira me) -s"In Progress" --plain --columns key,summary
|
||||
|
||||
echo ""
|
||||
echo "Closed this week:"
|
||||
jira issue list -a$(jira me) -sDone --updated week --plain --columns key,summary
|
||||
```
|
||||
|
||||
### Sprint Report Generator
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Generate sprint summary report
|
||||
|
||||
SPRINT_ID=$1
|
||||
|
||||
if [ -z "$SPRINT_ID" ]; then
|
||||
echo "Usage: $0 <sprint-id>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "=== Sprint Report for Sprint $SPRINT_ID ==="
|
||||
echo ""
|
||||
|
||||
total=$(jira sprint list "$SPRINT_ID" --plain --no-headers | wc -l)
|
||||
done_count=$(jira sprint list "$SPRINT_ID" -sDone --plain --no-headers | wc -l)
|
||||
in_progress=$(jira sprint list "$SPRINT_ID" -s"In Progress" --plain --no-headers | wc -l)
|
||||
todo=$(jira sprint list "$SPRINT_ID" -s"To Do" --plain --no-headers | wc -l)
|
||||
|
||||
echo "Total tickets: $total"
|
||||
echo "Done: $done_count"
|
||||
echo "In Progress: $in_progress"
|
||||
echo "To Do: $todo"
|
||||
echo ""
|
||||
|
||||
completion_rate=$(echo "scale=2; ($done_count / $total) * 100" | bc)
|
||||
echo "Completion rate: ${completion_rate}%"
|
||||
```
|
||||
|
||||
### Bulk Issue Assignment
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Assign unassigned high priority tickets to team members
|
||||
|
||||
# Get list of unassigned high priority tickets
|
||||
issues=$(jira issue list -ax -yHigh -s"To Do" --plain --columns key --no-headers)
|
||||
|
||||
# Team members
|
||||
team=("Alice" "Bob" "Charlie")
|
||||
team_size=${#team[@]}
|
||||
index=0
|
||||
|
||||
# Assign in round-robin fashion
|
||||
for issue in $issues; do
|
||||
assignee="${team[$index]}"
|
||||
echo "Assigning $issue to $assignee"
|
||||
jira issue assign "$issue" "$assignee"
|
||||
index=$(( (index + 1) % team_size ))
|
||||
done
|
||||
```
|
||||
|
||||
### Auto-Label Based on Summary
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Auto-label issues based on keywords in summary
|
||||
|
||||
# Get issues without labels
|
||||
issues=$(jira issue list --plain --columns key,summary --no-headers)
|
||||
|
||||
echo "$issues" | while IFS=$'\t' read -r key summary; do
|
||||
# Check for keywords and add labels
|
||||
if echo "$summary" | grep -qi "bug\|error\|crash"; then
|
||||
echo "Adding 'bug' label to $key"
|
||||
jira issue edit "$key" --label bug
|
||||
fi
|
||||
|
||||
if echo "$summary" | grep -qi "feature\|enhancement"; then
|
||||
echo "Adding 'enhancement' label to $key"
|
||||
jira issue edit "$key" --label enhancement
|
||||
fi
|
||||
|
||||
if echo "$summary" | grep -qi "urgent\|critical\|blocker"; then
|
||||
echo "Adding 'urgent' label to $key"
|
||||
jira issue edit "$key" --label urgent
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Export Issues to CSV
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Export filtered issues to CSV file
|
||||
|
||||
OUTPUT_FILE="issues_$(date +%Y%m%d).csv"
|
||||
|
||||
# Export with custom columns
|
||||
jira issue list \
|
||||
--created month \
|
||||
--csv \
|
||||
--columns key,type,status,priority,assignee,summary,created \
|
||||
> "$OUTPUT_FILE"
|
||||
|
||||
echo "Exported to $OUTPUT_FILE"
|
||||
```
|
||||
|
||||
### Monitor High Priority Issues
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Monitor and alert on high priority unassigned issues
|
||||
|
||||
THRESHOLD=5
|
||||
|
||||
count=$(jira issue list -ax -yHigh -s~Done --plain --no-headers | wc -l)
|
||||
|
||||
if [ "$count" -gt "$THRESHOLD" ]; then
|
||||
echo "⚠️ Alert: $count high priority unassigned issues (threshold: $THRESHOLD)"
|
||||
jira issue list -ax -yHigh -s~Done --plain --columns key,summary
|
||||
|
||||
# Could send to Slack, email, etc.
|
||||
# slack-cli send "#team-alerts" "High priority issues need attention: $count tickets"
|
||||
else
|
||||
echo "✅ OK: $count high priority unassigned issues"
|
||||
fi
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions - Create Jira Issue on PR
|
||||
|
||||
```yaml
|
||||
name: Create Jira Issue
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened]
|
||||
|
||||
jobs:
|
||||
create-jira:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Install jira-cli
|
||||
run: |
|
||||
wget https://github.com/ankitpokhrel/jira-cli/releases/latest/download/jira_linux_amd64.tar.gz
|
||||
tar -xf jira_linux_amd64.tar.gz
|
||||
sudo mv jira /usr/local/bin/
|
||||
|
||||
- name: Create Jira Issue
|
||||
env:
|
||||
JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
|
||||
JIRA_SERVER: ${{ secrets.JIRA_SERVER }}
|
||||
JIRA_PROJECT: ${{ secrets.JIRA_PROJECT }}
|
||||
run: |
|
||||
jira issue create \
|
||||
-tTask \
|
||||
-s"Review PR #${{ github.event.pull_request.number }}: ${{ github.event.pull_request.title }}" \
|
||||
-b"${{ github.event.pull_request.html_url }}" \
|
||||
--no-input
|
||||
```
|
||||
|
||||
### GitLab CI - Update Jira on Deploy
|
||||
|
||||
```yaml
|
||||
update_jira:
|
||||
stage: deploy
|
||||
script:
|
||||
- |
|
||||
# Extract Jira keys from commit messages
|
||||
JIRA_KEYS=$(git log --format=%B -n 10 | grep -oE '[A-Z]+-[0-9]+' | sort -u)
|
||||
|
||||
for KEY in $JIRA_KEYS; do
|
||||
echo "Updating $KEY to Done"
|
||||
jira issue move "$KEY" Done -RDeployed --comment "Deployed to production"
|
||||
done
|
||||
only:
|
||||
- main
|
||||
```
|
||||
|
||||
### Jenkins Pipeline - Sprint Metrics
|
||||
|
||||
```groovy
|
||||
pipeline {
|
||||
agent any
|
||||
triggers {
|
||||
cron('0 9 * * 1') // Every Monday at 9 AM
|
||||
}
|
||||
stages {
|
||||
stage('Generate Sprint Report') {
|
||||
steps {
|
||||
script {
|
||||
sh '''
|
||||
# Get current sprint
|
||||
SPRINT_ID=$(jira sprint list --current --table --plain --columns id --no-headers)
|
||||
|
||||
# Generate metrics
|
||||
echo "Sprint Metrics Report" > sprint_report.txt
|
||||
echo "===================" >> sprint_report.txt
|
||||
|
||||
total=$(jira sprint list $SPRINT_ID --plain --no-headers | wc -l)
|
||||
done=$(jira sprint list $SPRINT_ID -sDone --plain --no-headers | wc -l)
|
||||
|
||||
echo "Total: $total" >> sprint_report.txt
|
||||
echo "Done: $done" >> sprint_report.txt
|
||||
|
||||
# Send to team
|
||||
cat sprint_report.txt
|
||||
'''
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Data Analysis
|
||||
|
||||
### Export Data for Analysis
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Export comprehensive data for analysis
|
||||
|
||||
# Create timestamped directory
|
||||
DIR="jira_export_$(date +%Y%m%d_%H%M%S)"
|
||||
mkdir -p "$DIR"
|
||||
|
||||
# Export different views
|
||||
echo "Exporting all open issues..."
|
||||
jira issue list -s~Done --csv > "$DIR/open_issues.csv"
|
||||
|
||||
echo "Exporting completed this month..."
|
||||
jira issue list -sDone --updated month --csv > "$DIR/completed_month.csv"
|
||||
|
||||
echo "Exporting by assignee..."
|
||||
for user in $(jira issue list --plain --columns assignee --no-headers | sort -u); do
|
||||
jira issue list -a"$user" --csv > "$DIR/assignee_${user// /_}.csv"
|
||||
done
|
||||
|
||||
echo "Export complete in $DIR/"
|
||||
```
|
||||
|
||||
### Calculate Team Velocity
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Calculate team velocity over last N sprints
|
||||
|
||||
SPRINT_COUNT=5
|
||||
|
||||
echo "=== Team Velocity (last $SPRINT_COUNT sprints) ==="
|
||||
echo ""
|
||||
|
||||
sprints=$(jira sprint list --state closed --table --plain --columns id,name --no-headers | head -$SPRINT_COUNT)
|
||||
|
||||
total_points=0
|
||||
sprint_count=0
|
||||
|
||||
echo "$sprints" | while IFS=$'\t' read -r id name; do
|
||||
# Assuming story points in summary or custom field
|
||||
completed=$(jira sprint list "$id" -sDone --plain --no-headers | wc -l)
|
||||
echo "$name: $completed stories"
|
||||
|
||||
total_points=$((total_points + completed))
|
||||
sprint_count=$((sprint_count + 1))
|
||||
done
|
||||
|
||||
# Calculate average
|
||||
if [ $sprint_count -gt 0 ]; then
|
||||
avg=$(echo "scale=2; $total_points / $sprint_count" | bc)
|
||||
echo ""
|
||||
echo "Average velocity: $avg stories per sprint"
|
||||
fi
|
||||
```
|
||||
|
||||
## Automation Helpers
|
||||
|
||||
### Auto-Transition Based on PR Status
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Auto-transition Jira issues based on PR status
|
||||
|
||||
# Get list of open PRs from GitHub
|
||||
# (requires gh CLI)
|
||||
prs=$(gh pr list --json number,title --jq '.[] | "\(.number)|\(.title)"')
|
||||
|
||||
echo "$prs" | while IFS='|' read -r number title; do
|
||||
# Extract Jira key from PR title
|
||||
jira_key=$(echo "$title" | grep -oE '[A-Z]+-[0-9]+' | head -1)
|
||||
|
||||
if [ -n "$jira_key" ]; then
|
||||
# Check current status
|
||||
status=$(jira issue view "$jira_key" --plain | grep "Status:" | awk '{print $2}')
|
||||
|
||||
# Move to In Review if not already
|
||||
if [ "$status" != "Review" ]; then
|
||||
echo "Moving $jira_key to In Review (PR #$number)"
|
||||
jira issue move "$jira_key" "In Review"
|
||||
jira issue link remote "$jira_key" "https://github.com/org/repo/pull/$number" "PR #$number"
|
||||
fi
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Stale Issue Cleanup
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# Find and handle stale issues
|
||||
|
||||
# Find issues not updated in 3 months
|
||||
stale=$(jira issue list --updated-before -12w -s"To Do" --plain --columns key,summary --no-headers)
|
||||
|
||||
echo "$stale" | while IFS=$'\t' read -r key summary; do
|
||||
echo "Stale issue found: $key - $summary"
|
||||
|
||||
# Add comment asking for update
|
||||
jira issue comment add "$key" "This issue hasn't been updated in 3 months. Is it still relevant?"
|
||||
|
||||
# Add stale label
|
||||
jira issue edit "$key" --label stale
|
||||
|
||||
# Optionally: move to backlog or close
|
||||
# jira issue move "$key" "Backlog"
|
||||
done
|
||||
```
|
||||
|
||||
## Best Practices for Scripts
|
||||
|
||||
### Error Handling
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail # Exit on error, undefined vars, pipe failures
|
||||
|
||||
# Check if jira-cli is available
|
||||
if ! command -v jira &> /dev/null; then
|
||||
echo "Error: jira-cli not found. Please install it first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for required environment variables
|
||||
if [ -z "${JIRA_API_TOKEN:-}" ]; then
|
||||
echo "Error: JIRA_API_TOKEN not set"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Wrap jira commands with error handling
|
||||
if ! jira issue list -a$(jira me) 2>&1; then
|
||||
echo "Error: Failed to fetch issues"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Logging and Debugging
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# Enable debug mode
|
||||
DEBUG=${DEBUG:-false}
|
||||
|
||||
debug() {
|
||||
if [ "$DEBUG" = "true" ]; then
|
||||
echo "[DEBUG] $*" >&2
|
||||
fi
|
||||
}
|
||||
|
||||
debug "Starting script..."
|
||||
debug "Fetching issues for user: $(jira me)"
|
||||
|
||||
issues=$(jira issue list -a$(jira me) --plain --columns key --no-headers)
|
||||
debug "Found $(echo "$issues" | wc -l) issues"
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
|
||||
# Process issues with rate limiting
|
||||
issues=$(jira issue list --plain --columns key --no-headers)
|
||||
|
||||
for issue in $issues; do
|
||||
echo "Processing $issue"
|
||||
jira issue view "$issue" > /dev/null
|
||||
|
||||
# Rate limit: 1 request per second
|
||||
sleep 1
|
||||
done
|
||||
```
|
||||
290
skills/jira-cli/references/workflows.md
Normal file
290
skills/jira-cli/references/workflows.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# Jira CLI - Common Workflows
|
||||
|
||||
This file contains practical workflow examples for common Jira use cases and team collaboration scenarios.
|
||||
|
||||
## Daily Standup Preparation
|
||||
|
||||
Get quick answers for your daily standup:
|
||||
|
||||
```bash
|
||||
# What did I work on yesterday?
|
||||
jira issue list -a$(jira me) --updated -1d
|
||||
|
||||
# What am I working on today?
|
||||
jira issue list -a$(jira me) -s"In Progress"
|
||||
|
||||
# What tickets did I close this week?
|
||||
jira issue list -a$(jira me) -sDone --updated week
|
||||
|
||||
# Any blockers? (high priority issues assigned to me)
|
||||
jira issue list -a$(jira me) -yHigh -s~Done
|
||||
```
|
||||
|
||||
## Sprint Planning
|
||||
|
||||
Prepare for and manage sprint planning:
|
||||
|
||||
```bash
|
||||
# High priority unassigned tickets (need assignment)
|
||||
jira issue list -ax -yHigh
|
||||
|
||||
# Backlog items ready for sprint (ordered by rank like UI)
|
||||
jira issue list -s"Ready for Dev" --order-by rank --reverse
|
||||
|
||||
# Current sprint progress
|
||||
jira sprint list --current
|
||||
|
||||
# Current sprint with my tasks only
|
||||
jira sprint list --current -a$(jira me)
|
||||
|
||||
# See what's planned for next sprint
|
||||
jira sprint list --next
|
||||
|
||||
# Check sprint capacity (how many issues)
|
||||
jira sprint list SPRINT_ID --plain --no-headers | wc -l
|
||||
```
|
||||
|
||||
## Code Review Workflow
|
||||
|
||||
Integrate Jira with your code review process:
|
||||
|
||||
```bash
|
||||
# 1. Create ticket for review
|
||||
jira issue create -tTask -s"Code review: Feature X"
|
||||
|
||||
# 2. Link to related PR
|
||||
jira issue link remote ISSUE-1 https://github.com/org/repo/pull/123 "PR #123"
|
||||
|
||||
# 3. Move to review status
|
||||
jira issue move ISSUE-1 "In Review"
|
||||
|
||||
# 4. Add review comments
|
||||
jira issue comment add ISSUE-1 "LGTM! Approved changes."
|
||||
|
||||
# 5. Close the ticket
|
||||
jira issue move ISSUE-1 Done -RFixed
|
||||
```
|
||||
|
||||
## Bug Triage
|
||||
|
||||
Efficient bug triage workflow:
|
||||
|
||||
```bash
|
||||
# List new bugs from last week
|
||||
jira issue list -tBug -sOpen --created -7d
|
||||
|
||||
# List critical/high priority bugs
|
||||
jira issue list -tBug -yHighest,High -s~Done
|
||||
|
||||
# Assign high priority bug to team lead
|
||||
jira issue assign BUG-123 "Team Lead"
|
||||
|
||||
# Add triage notes
|
||||
jira issue comment add BUG-123 "Investigating root cause. Checking logs."
|
||||
|
||||
# Update priority and labels
|
||||
jira issue edit BUG-123 -yHigh -lproduction -lurgent
|
||||
|
||||
# Link to related issues
|
||||
jira issue link BUG-123 BUG-100 "is caused by"
|
||||
```
|
||||
|
||||
## Epic Management Workflow
|
||||
|
||||
Working with epics effectively:
|
||||
|
||||
```bash
|
||||
# Create a new epic for quarterly goals
|
||||
jira epic create -n"Q1 2025 Goals" -s"Q1 Goals" -yHigh
|
||||
|
||||
# List open epics to see what's in progress
|
||||
jira epic list -sOpen
|
||||
|
||||
# View all tasks in a specific epic
|
||||
jira epic list EPIC-42
|
||||
|
||||
# Add new stories to the epic
|
||||
jira issue create -tStory -s"User authentication" -PEPIC-42
|
||||
jira epic add EPIC-42 STORY-100 STORY-101
|
||||
|
||||
# Check epic progress (how many done vs total)
|
||||
jira epic list EPIC-42 -sDone --plain --no-headers | wc -l
|
||||
jira epic list EPIC-42 --plain --no-headers | wc -l
|
||||
|
||||
# Remove completed stories from epic
|
||||
jira epic remove STORY-98 STORY-99
|
||||
```
|
||||
|
||||
## Release Management
|
||||
|
||||
Managing releases and versions:
|
||||
|
||||
```bash
|
||||
# List all releases
|
||||
jira release list
|
||||
|
||||
# List releases for specific project
|
||||
jira release list --project MYPROJECT
|
||||
|
||||
# Create issues for a release
|
||||
jira issue create -tBug -s"Release blocker" --fix-version v2.0
|
||||
|
||||
# Find all issues in a release
|
||||
jira issue list --fix-version v2.0
|
||||
|
||||
# Find unresolved issues blocking release
|
||||
jira issue list --fix-version v2.0 -s~Done
|
||||
```
|
||||
|
||||
## Team Collaboration
|
||||
|
||||
Collaborate effectively with your team:
|
||||
|
||||
```bash
|
||||
# See what your teammate is working on
|
||||
jira issue list -a"John Doe" -s"In Progress"
|
||||
|
||||
# Find issues reported by PM for review
|
||||
jira issue list -r"Jane PM" -s"To Do" --order-by priority
|
||||
|
||||
# Check team's completed work this week
|
||||
jira issue list -a~x --updated week -sDone
|
||||
|
||||
# Find unassigned high priority work
|
||||
jira issue list -ax -yHigh -s"To Do"
|
||||
|
||||
# Check who's working on what in current sprint
|
||||
jira sprint list --current --plain --columns assignee,key,summary
|
||||
```
|
||||
|
||||
## Incident Response
|
||||
|
||||
Handle production incidents:
|
||||
|
||||
```bash
|
||||
# Create critical incident ticket
|
||||
jira issue create -tBug -s"Production outage: API down" -yHighest -lincident -lproduction --no-input
|
||||
|
||||
# Link related issues
|
||||
jira issue link INC-1 BUG-789 "is caused by"
|
||||
|
||||
# Add status updates
|
||||
jira issue comment add INC-1 "Root cause identified. Rolling back deployment."
|
||||
|
||||
# Track time spent
|
||||
jira issue worklog add INC-1 "2h" --comment "Incident response" --no-input
|
||||
|
||||
# Close incident
|
||||
jira issue move INC-1 Done -RFixed --comment "Service restored. Post-mortem scheduled."
|
||||
```
|
||||
|
||||
## Backlog Grooming
|
||||
|
||||
Keep your backlog organized:
|
||||
|
||||
```bash
|
||||
# Find old unassigned tickets (potential cleanup candidates)
|
||||
jira issue list -ax --created-before -12w -s"To Do"
|
||||
|
||||
# Find tickets with no recent activity
|
||||
jira issue list --updated-before -8w -s~Done
|
||||
|
||||
# Find tickets missing labels or components
|
||||
jira issue list -l~x -C~x
|
||||
|
||||
# Update stale tickets in bulk (interactive or scripted)
|
||||
for issue in $(jira issue list -ax --created-before -12w --plain --columns key --no-headers); do
|
||||
jira issue edit $issue -s"To Do" --label stale
|
||||
done
|
||||
```
|
||||
|
||||
## Cross-Team Coordination
|
||||
|
||||
Working across teams:
|
||||
|
||||
```bash
|
||||
# Find issues blocked by other teams
|
||||
jira issue list -a$(jira me) -lblocked --plain --columns key,summary,status
|
||||
|
||||
# Check dependencies in a project
|
||||
jira issue list -pOTHERPROJ -a"Dependency Owner"
|
||||
|
||||
# See what other teams need from you
|
||||
jira issue list -r~$(jira me) -a$(jira me) --plain --columns key,reporter,summary
|
||||
|
||||
# Create handoff ticket
|
||||
jira issue create -tTask -s"Handoff: Database migration" -CInfra -a"Infrastructure Lead"
|
||||
```
|
||||
|
||||
## Personal Productivity
|
||||
|
||||
Personal task management:
|
||||
|
||||
```bash
|
||||
# My daily dashboard
|
||||
alias jira-today='jira issue list -a$(jira me) -s"In Progress"'
|
||||
|
||||
# What I should focus on
|
||||
alias jira-priorities='jira issue list -a$(jira me) -yHigh -s~Done --order-by priority'
|
||||
|
||||
# What I reported that needs attention
|
||||
alias jira-reported='jira issue list -r$(jira me) -s"To Do"'
|
||||
|
||||
# Quick add task
|
||||
alias jira-task='jira issue create -tTask -a$(jira me)'
|
||||
|
||||
# My work this week
|
||||
alias jira-week='jira issue list -a$(jira me) --updated week'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Efficient Filtering
|
||||
|
||||
```bash
|
||||
# Combine multiple filters for precision
|
||||
jira issue list -a$(jira me) -yHigh -s"In Progress" --created week -lurgent
|
||||
|
||||
# Use NOT operator (~) to exclude
|
||||
jira issue list -s~Done -s~"In Progress" # Not done and not in progress
|
||||
|
||||
# Time-based queries for recent activity
|
||||
jira issue list --updated -2h # Last 2 hours
|
||||
jira issue list --created today # Created today
|
||||
```
|
||||
|
||||
### Bulk Operations
|
||||
|
||||
```bash
|
||||
# Add multiple issues to sprint
|
||||
jira sprint add SPRINT_ID $(jira issue list -s"Ready" --plain --columns key --no-headers | head -10 | tr '\n' ' ')
|
||||
|
||||
# Batch assign to team members
|
||||
for issue in ISSUE-1 ISSUE-2 ISSUE-3; do
|
||||
jira issue assign $issue "Team Member"
|
||||
done
|
||||
```
|
||||
|
||||
### Keyboard Shortcuts in Interactive Mode
|
||||
|
||||
Master the interactive UI for speed:
|
||||
- Use **j/k** instead of arrows for Vim-like navigation
|
||||
- Press **v** to quickly view details without leaving the list
|
||||
- Press **m** to transition without navigating to browser
|
||||
- Use **c** and **CTRL+k** to quickly copy links/keys for sharing
|
||||
|
||||
### Output Formatting for Different Needs
|
||||
|
||||
```bash
|
||||
# For spreadsheets
|
||||
jira issue list --csv > issues.csv
|
||||
|
||||
# For scripts
|
||||
jira issue list --plain --no-headers --columns key
|
||||
|
||||
# For reports
|
||||
jira issue list --plain --columns key,status,assignee,summary
|
||||
|
||||
# For JSON processing
|
||||
jira issue list --raw | jq '.issues[] | {key, summary}'
|
||||
```
|
||||
201
skills/skill-creator/LICENSE.txt
Normal file
201
skills/skill-creator/LICENSE.txt
Normal file
@@ -0,0 +1,201 @@
|
||||
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.
|
||||
209
skills/skill-creator/SKILL.md
Normal file
209
skills/skill-creator/SKILL.md
Normal file
@@ -0,0 +1,209 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
|
||||
license: Complete terms in LICENSE.txt
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
This skill provides guidance for creating effective skills.
|
||||
|
||||
## About Skills
|
||||
|
||||
Skills are modular, self-contained packages that extend Claude's capabilities by providing
|
||||
specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
|
||||
domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
|
||||
equipped with procedural knowledge that no model can fully possess.
|
||||
|
||||
### What Skills Provide
|
||||
|
||||
1. Specialized workflows - Multi-step procedures for specific domains
|
||||
2. Tool integrations - Instructions for working with specific file formats or APIs
|
||||
3. Domain expertise - Company-specific knowledge, schemas, business logic
|
||||
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
|
||||
|
||||
### Anatomy of a Skill
|
||||
|
||||
Every skill consists of a required SKILL.md file and optional bundled resources:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required)
|
||||
│ ├── YAML frontmatter metadata (required)
|
||||
│ │ ├── name: (required)
|
||||
│ │ └── description: (required)
|
||||
│ └── Markdown instructions (required)
|
||||
└── Bundled Resources (optional)
|
||||
├── scripts/ - Executable code (Python/Bash/etc.)
|
||||
├── references/ - Documentation intended to be loaded into context as needed
|
||||
└── assets/ - Files used in output (templates, icons, fonts, etc.)
|
||||
```
|
||||
|
||||
#### SKILL.md (required)
|
||||
|
||||
**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").
|
||||
|
||||
#### Bundled Resources (optional)
|
||||
|
||||
##### Scripts (`scripts/`)
|
||||
|
||||
Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
|
||||
|
||||
- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
|
||||
- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
|
||||
- **Benefits**: Token efficient, deterministic, may be executed without loading into context
|
||||
- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
|
||||
|
||||
##### References (`references/`)
|
||||
|
||||
Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
|
||||
|
||||
- **When to include**: For documentation that Claude should reference while working
|
||||
- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
|
||||
- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
|
||||
- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
|
||||
- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
|
||||
- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
|
||||
|
||||
##### Assets (`assets/`)
|
||||
|
||||
Files not intended to be loaded into context, but rather used within the output Claude produces.
|
||||
|
||||
- **When to include**: When the skill needs files that will be used in the final output
|
||||
- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
|
||||
- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
|
||||
- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
|
||||
|
||||
### Progressive Disclosure Design Principle
|
||||
|
||||
Skills use a three-level loading system to manage context efficiently:
|
||||
|
||||
1. **Metadata (name + description)** - Always in context (~100 words)
|
||||
2. **SKILL.md body** - When skill triggers (<5k words)
|
||||
3. **Bundled resources** - As needed by Claude (Unlimited*)
|
||||
|
||||
*Unlimited because scripts can be executed without reading into context window.
|
||||
|
||||
## Skill Creation Process
|
||||
|
||||
To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.
|
||||
|
||||
### Step 1: Understanding the Skill with Concrete Examples
|
||||
|
||||
Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
|
||||
|
||||
To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
|
||||
|
||||
For example, when building an image-editor skill, relevant questions include:
|
||||
|
||||
- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
|
||||
- "Can you give some examples of how this skill would be used?"
|
||||
- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
|
||||
- "What would a user say that should trigger this skill?"
|
||||
|
||||
To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
|
||||
|
||||
Conclude this step when there is a clear sense of the functionality the skill should support.
|
||||
|
||||
### Step 2: Planning the Reusable Skill Contents
|
||||
|
||||
To turn concrete examples into an effective skill, analyze each example by:
|
||||
|
||||
1. Considering how to execute on the example from scratch
|
||||
2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
|
||||
|
||||
Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
|
||||
|
||||
1. Rotating a PDF requires re-writing the same code each time
|
||||
2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
|
||||
|
||||
Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
|
||||
|
||||
1. Writing a frontend webapp requires the same boilerplate HTML/React each time
|
||||
2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
|
||||
|
||||
Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
|
||||
|
||||
1. Querying BigQuery requires re-discovering the table schemas and relationships each time
|
||||
2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
|
||||
|
||||
To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
|
||||
|
||||
### Step 3: Initializing the Skill
|
||||
|
||||
At this point, it is time to actually create the skill.
|
||||
|
||||
Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
|
||||
|
||||
When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
|
||||
|
||||
Usage:
|
||||
|
||||
```bash
|
||||
scripts/init_skill.py <skill-name> --path <output-directory>
|
||||
```
|
||||
|
||||
The script:
|
||||
|
||||
- Creates the skill directory at the specified path
|
||||
- Generates a SKILL.md template with proper frontmatter and TODO placeholders
|
||||
- Creates example resource directories: `scripts/`, `references/`, and `assets/`
|
||||
- Adds example files in each directory that can be customized or deleted
|
||||
|
||||
After initialization, customize or remove the generated SKILL.md and example files as needed.
|
||||
|
||||
### Step 4: Edit the Skill
|
||||
|
||||
When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
|
||||
|
||||
#### Start with Reusable Skill Contents
|
||||
|
||||
To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
|
||||
|
||||
Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.
|
||||
|
||||
#### Update SKILL.md
|
||||
|
||||
**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.
|
||||
|
||||
To complete SKILL.md, answer the following questions:
|
||||
|
||||
1. What is the purpose of the skill, in a few sentences?
|
||||
2. When should the skill be used?
|
||||
3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.
|
||||
|
||||
### Step 5: Packaging a Skill
|
||||
|
||||
Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
|
||||
|
||||
```bash
|
||||
scripts/package_skill.py <path/to/skill-folder>
|
||||
```
|
||||
|
||||
Optional output directory specification:
|
||||
|
||||
```bash
|
||||
scripts/package_skill.py <path/to/skill-folder> ./dist
|
||||
```
|
||||
|
||||
The packaging script will:
|
||||
|
||||
1. **Validate** the skill automatically, checking:
|
||||
- YAML frontmatter format and required fields
|
||||
- Skill naming conventions and directory structure
|
||||
- Description completeness and quality
|
||||
- File organization and resource references
|
||||
|
||||
2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution.
|
||||
|
||||
If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
|
||||
|
||||
### Step 6: Iterate
|
||||
|
||||
After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
|
||||
|
||||
**Iteration workflow:**
|
||||
1. Use the skill on real tasks
|
||||
2. Notice struggles or inefficiencies
|
||||
3. Identify how SKILL.md or bundled resources should be updated
|
||||
4. Implement changes and test again
|
||||
271
skills/skill-creator/scripts/init_skill.py
Executable file
271
skills/skill-creator/scripts/init_skill.py
Executable file
@@ -0,0 +1,271 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Skill Initializer - Creates a new skill from template
|
||||
|
||||
Usage:
|
||||
init_skill.py <skill-name> --path <path>
|
||||
|
||||
Examples:
|
||||
init_skill.py my-new-skill --path skills/public
|
||||
init_skill.py my-api-helper --path skills/private
|
||||
init_skill.py custom-skill --path /custom/location
|
||||
"""
|
||||
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
SKILL_TEMPLATE = """---
|
||||
name: {skill_name}
|
||||
description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
|
||||
---
|
||||
|
||||
# {skill_title}
|
||||
|
||||
## Overview
|
||||
|
||||
[TODO: 1-2 sentences explaining what this skill enables]
|
||||
|
||||
## Structuring This Skill
|
||||
|
||||
[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
|
||||
|
||||
**1. Workflow-Based** (best for sequential processes)
|
||||
- Works well when there are clear step-by-step procedures
|
||||
- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
|
||||
- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
|
||||
|
||||
**2. Task-Based** (best for tool collections)
|
||||
- Works well when the skill offers different operations/capabilities
|
||||
- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
|
||||
- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
|
||||
|
||||
**3. Reference/Guidelines** (best for standards or specifications)
|
||||
- Works well for brand guidelines, coding standards, or requirements
|
||||
- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
|
||||
- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
|
||||
|
||||
**4. Capabilities-Based** (best for integrated systems)
|
||||
- Works well when the skill provides multiple interrelated features
|
||||
- Example: Product Management with "Core Capabilities" → numbered capability list
|
||||
- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
|
||||
|
||||
Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
|
||||
|
||||
Delete this entire "Structuring This Skill" section when done - it's just guidance.]
|
||||
|
||||
## [TODO: Replace with the first main section based on chosen structure]
|
||||
|
||||
[TODO: Add content here. See examples in existing skills:
|
||||
- Code samples for technical skills
|
||||
- Decision trees for complex workflows
|
||||
- Concrete examples with realistic user requests
|
||||
- References to scripts/templates/references as needed]
|
||||
|
||||
## Resources
|
||||
|
||||
This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
|
||||
|
||||
### scripts/
|
||||
Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
|
||||
|
||||
**Examples from other skills:**
|
||||
- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
|
||||
- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
|
||||
|
||||
**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
|
||||
|
||||
**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
|
||||
|
||||
### references/
|
||||
Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
|
||||
|
||||
**Examples from other skills:**
|
||||
- Product management: `communication.md`, `context_building.md` - detailed workflow guides
|
||||
- BigQuery: API reference documentation and query examples
|
||||
- Finance: Schema documentation, company policies
|
||||
|
||||
**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
|
||||
|
||||
### assets/
|
||||
Files not intended to be loaded into context, but rather used within the output Claude produces.
|
||||
|
||||
**Examples from other skills:**
|
||||
- Brand styling: PowerPoint template files (.pptx), logo files
|
||||
- Frontend builder: HTML/React boilerplate project directories
|
||||
- Typography: Font files (.ttf, .woff2)
|
||||
|
||||
**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
|
||||
|
||||
---
|
||||
|
||||
**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
|
||||
"""
|
||||
|
||||
EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
|
||||
"""
|
||||
Example helper script for {skill_name}
|
||||
|
||||
This is a placeholder script that can be executed directly.
|
||||
Replace with actual implementation or delete if not needed.
|
||||
|
||||
Example real scripts from other skills:
|
||||
- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
|
||||
- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
|
||||
"""
|
||||
|
||||
def main():
|
||||
print("This is an example script for {skill_name}")
|
||||
# TODO: Add actual script logic here
|
||||
# This could be data processing, file conversion, API calls, etc.
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
'''
|
||||
|
||||
EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
|
||||
|
||||
This is a placeholder for detailed reference documentation.
|
||||
Replace with actual reference content or delete if not needed.
|
||||
|
||||
Example real reference docs from other skills:
|
||||
- product-management/references/communication.md - Comprehensive guide for status updates
|
||||
- product-management/references/context_building.md - Deep-dive on gathering context
|
||||
- bigquery/references/ - API references and query examples
|
||||
|
||||
## When Reference Docs Are Useful
|
||||
|
||||
Reference docs are ideal for:
|
||||
- Comprehensive API documentation
|
||||
- Detailed workflow guides
|
||||
- Complex multi-step processes
|
||||
- Information too lengthy for main SKILL.md
|
||||
- Content that's only needed for specific use cases
|
||||
|
||||
## Structure Suggestions
|
||||
|
||||
### API Reference Example
|
||||
- Overview
|
||||
- Authentication
|
||||
- Endpoints with examples
|
||||
- Error codes
|
||||
- Rate limits
|
||||
|
||||
### Workflow Guide Example
|
||||
- Prerequisites
|
||||
- Step-by-step instructions
|
||||
- Common patterns
|
||||
- Troubleshooting
|
||||
- Best practices
|
||||
"""
|
||||
|
||||
EXAMPLE_ASSET = """# Example Asset File
|
||||
|
||||
This placeholder represents where asset files would be stored.
|
||||
Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
|
||||
|
||||
Asset files are NOT intended to be loaded into context, but rather used within
|
||||
the output Claude produces.
|
||||
|
||||
Example asset files from other skills:
|
||||
- Brand guidelines: logo.png, slides_template.pptx
|
||||
- Frontend builder: hello-world/ directory with HTML/React boilerplate
|
||||
- Typography: custom-font.ttf, font-family.woff2
|
||||
- Data: sample_data.csv, test_dataset.json
|
||||
|
||||
## Common Asset Types
|
||||
|
||||
- Templates: .pptx, .docx, boilerplate directories
|
||||
- Images: .png, .jpg, .svg, .gif
|
||||
- Fonts: .ttf, .otf, .woff, .woff2
|
||||
- Boilerplate code: Project directories, starter files
|
||||
- Icons: .ico, .svg
|
||||
- Data files: .csv, .json, .xml, .yaml
|
||||
|
||||
Note: This is a text placeholder. Actual assets can be any file type.
|
||||
"""
|
||||
|
||||
|
||||
def title_case_skill_name(skill_name):
|
||||
"""Convert hyphenated skill name to Title Case for display."""
|
||||
return ' '.join(word.capitalize() for word in skill_name.split('-'))
|
||||
|
||||
|
||||
def init_skill(skill_name, path):
|
||||
"""
|
||||
Initialize a new skill directory with template SKILL.md.
|
||||
|
||||
Args:
|
||||
skill_name: Name of the skill
|
||||
path: Path where the skill directory should be created
|
||||
|
||||
Returns:
|
||||
Path to created skill directory, or None if error
|
||||
"""
|
||||
# Determine skill directory path
|
||||
skill_dir = Path(path).resolve() / skill_name
|
||||
|
||||
# Check if directory already exists
|
||||
if skill_dir.exists():
|
||||
return None
|
||||
|
||||
# Create skill directory
|
||||
try:
|
||||
skill_dir.mkdir(parents=True, exist_ok=False)
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
# Create SKILL.md from template
|
||||
skill_title = title_case_skill_name(skill_name)
|
||||
skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)
|
||||
|
||||
skill_md_path = skill_dir / 'SKILL.md'
|
||||
try:
|
||||
skill_md_path.write_text(skill_content)
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
# Create resource directories with example files
|
||||
try:
|
||||
# Create scripts/ directory with example script
|
||||
scripts_dir = skill_dir / 'scripts'
|
||||
scripts_dir.mkdir(exist_ok=True)
|
||||
example_script = scripts_dir / 'example.py'
|
||||
example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
|
||||
example_script.chmod(0o755)
|
||||
|
||||
# Create references/ directory with example reference doc
|
||||
references_dir = skill_dir / 'references'
|
||||
references_dir.mkdir(exist_ok=True)
|
||||
example_reference = references_dir / 'api_reference.md'
|
||||
example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
|
||||
|
||||
# Create assets/ directory with example asset placeholder
|
||||
assets_dir = skill_dir / 'assets'
|
||||
assets_dir.mkdir(exist_ok=True)
|
||||
example_asset = assets_dir / 'example_asset.txt'
|
||||
example_asset.write_text(EXAMPLE_ASSET)
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
# Print next steps
|
||||
|
||||
return skill_dir
|
||||
|
||||
|
||||
def main() -> None:
|
||||
if len(sys.argv) < 4 or sys.argv[2] != '--path':
|
||||
sys.exit(1)
|
||||
|
||||
skill_name = sys.argv[1]
|
||||
path = sys.argv[3]
|
||||
|
||||
result = init_skill(skill_name, path)
|
||||
|
||||
if result:
|
||||
sys.exit(0)
|
||||
else:
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
95
skills/skill-creator/scripts/package_skill.py
Executable file
95
skills/skill-creator/scripts/package_skill.py
Executable file
@@ -0,0 +1,95 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Skill Packager - Creates a distributable zip file of a skill folder
|
||||
|
||||
Usage:
|
||||
python utils/package_skill.py <path/to/skill-folder> [output-directory]
|
||||
|
||||
Example:
|
||||
python utils/package_skill.py skills/public/my-skill
|
||||
python utils/package_skill.py skills/public/my-skill ./dist
|
||||
"""
|
||||
|
||||
import sys
|
||||
import zipfile
|
||||
from pathlib import Path
|
||||
|
||||
from quick_validate import validate_skill
|
||||
|
||||
|
||||
def package_skill(skill_path, output_dir=None):
|
||||
"""
|
||||
Package a skill folder into a zip file.
|
||||
|
||||
Args:
|
||||
skill_path: Path to the skill folder
|
||||
output_dir: Optional output directory for the zip file (defaults to current directory)
|
||||
|
||||
Returns:
|
||||
Path to the created zip file, or None if error
|
||||
"""
|
||||
skill_path = Path(skill_path).resolve()
|
||||
|
||||
# Validate skill folder exists
|
||||
if not skill_path.exists():
|
||||
return None
|
||||
|
||||
if not skill_path.is_dir():
|
||||
return None
|
||||
|
||||
# Validate SKILL.md exists
|
||||
skill_md = skill_path / 'SKILL.md'
|
||||
if not skill_md.exists():
|
||||
return None
|
||||
|
||||
# Run validation before packaging
|
||||
valid, message = validate_skill(skill_path)
|
||||
if not valid:
|
||||
return None
|
||||
|
||||
# Determine output location
|
||||
skill_name = skill_path.name
|
||||
if output_dir:
|
||||
output_path = Path(output_dir).resolve()
|
||||
output_path.mkdir(parents=True, exist_ok=True)
|
||||
else:
|
||||
output_path = Path.cwd()
|
||||
|
||||
zip_filename = output_path / f'{skill_name}.zip'
|
||||
|
||||
# Create the zip file
|
||||
try:
|
||||
with zipfile.ZipFile(zip_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
|
||||
# Walk through the skill directory
|
||||
for file_path in skill_path.rglob('*'):
|
||||
if file_path.is_file():
|
||||
# Calculate the relative path within the zip
|
||||
arcname = file_path.relative_to(skill_path.parent)
|
||||
zipf.write(file_path, arcname)
|
||||
|
||||
return zip_filename
|
||||
|
||||
except Exception:
|
||||
return None
|
||||
|
||||
|
||||
def main() -> None:
|
||||
if len(sys.argv) < 2:
|
||||
sys.exit(1)
|
||||
|
||||
skill_path = sys.argv[1]
|
||||
output_dir = sys.argv[2] if len(sys.argv) > 2 else None
|
||||
|
||||
if output_dir:
|
||||
pass
|
||||
|
||||
result = package_skill(skill_path, output_dir)
|
||||
|
||||
if result:
|
||||
sys.exit(0)
|
||||
else:
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
70
skills/skill-creator/scripts/quick_validate.py
Executable file
70
skills/skill-creator/scripts/quick_validate.py
Executable file
@@ -0,0 +1,70 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Quick validation script for skills - minimal version
|
||||
"""
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def validate_skill(skill_path):
|
||||
"""Basic validation of a skill"""
|
||||
skill_path = Path(skill_path)
|
||||
|
||||
# Check SKILL.md exists
|
||||
skill_md = skill_path / 'SKILL.md'
|
||||
if not skill_md.exists():
|
||||
return False, 'SKILL.md not found'
|
||||
|
||||
# Read and validate frontmatter
|
||||
content = skill_md.read_text()
|
||||
if not content.startswith('---'):
|
||||
return False, 'No YAML frontmatter found'
|
||||
|
||||
# Extract frontmatter
|
||||
match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
|
||||
if not match:
|
||||
return False, 'Invalid frontmatter format'
|
||||
|
||||
frontmatter = match.group(1)
|
||||
|
||||
# Check required fields
|
||||
if 'name:' not in frontmatter:
|
||||
return False, "Missing 'name' in frontmatter"
|
||||
if 'description:' not in frontmatter:
|
||||
return False, "Missing 'description' in frontmatter"
|
||||
|
||||
# Extract name for validation
|
||||
name_match = re.search(r'name:\s*(.+)', frontmatter)
|
||||
if name_match:
|
||||
name = name_match.group(1).strip()
|
||||
# Check naming convention (hyphen-case: lowercase with hyphens)
|
||||
if not re.match(r'^[a-z0-9-]+$', name):
|
||||
return (
|
||||
False,
|
||||
f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)",
|
||||
)
|
||||
if name.startswith('-') or name.endswith('-') or '--' in name:
|
||||
return (
|
||||
False,
|
||||
f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens",
|
||||
)
|
||||
|
||||
# Extract and validate description
|
||||
desc_match = re.search(r'description:\s*(.+)', frontmatter)
|
||||
if desc_match:
|
||||
description = desc_match.group(1).strip()
|
||||
# Check for angle brackets
|
||||
if '<' in description or '>' in description:
|
||||
return False, 'Description cannot contain angle brackets (< or >)'
|
||||
|
||||
return True, 'Skill is valid!'
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
if len(sys.argv) != 2:
|
||||
sys.exit(1)
|
||||
|
||||
valid, message = validate_skill(sys.argv[1])
|
||||
sys.exit(0 if valid else 1)
|
||||
Reference in New Issue
Block a user