YouTrack Project Management

Interact with YouTrack project management system via REST API. Read projects and issues, create tasks, generate invoices from time tracking data, and manage knowledge base articles. Use for reading projects and work items, creating or updating issues, generating client invoices from time tracking, and working with knowledge base articles.

Security Scan

The skill appears to implement a legitimate YouTrack client and invoice generator, but its metadata omits the required API token and a few implementation/instruction details are inconsistent — the omission should be resolved before trusting it with credentials.

Purpose & Capability

Name, description, and included code (youtrack_api.py and invoice_generator.py) align: the skill only targets YouTrack operations (projects, issues, work items, articles) and invoice generation from time tracking.

Instruction Scope

SKILL.md instructs the agent and user to use a YouTrack permanent token (YOUTRACK_TOKEN) and only describes YouTrack API calls and invoice generation. The runtime instructions do not request unrelated files, system settings, or external endpoints beyond the user's YouTrack instance.

Install Mechanism

No install spec is provided (instruction-only). Code files are included but nothing is downloaded or executed automatically by an installer. This is low-risk from an installation perspective.

Credentials

SKILL.md and the code clearly require an API token via YOUTRACK_TOKEN (or a --token argument), but the registry metadata lists no required environment variables and no primary credential. That mismatch is an incoherence: the skill will fail without a token and the metadata omission could mislead users into thinking no secrets are needed. Aside from that, requesting a single YouTrack token is proportionate to the described functionality.

Persistence & Privilege

The skill does not request always:true and does not attempt to modify other skills or system-wide settings. It runs as a normal, user-invoked skill and has no elevated persistence privileges.

What to consider before installing

This skill's code and instructions look coherent for interacting with YouTrack and generating invoices, but the registry metadata incorrectly omits the required API token (YOUTRACK_TOKEN). Before installing or running: 1) Treat your YouTrack token as a secret — only provide a least-privilege token and preferably create a dedicated service account or token with minimal scope. 2) Verify the registry metadata is corrected (it should declare YOUTRACK_TOKEN as a required credential/primaryEnv). 3) Inspect the included scripts locally (they use only your-instance.youtrack.cloud and standard urllib) and run them in a sandbox or with a test token first. 4) Consider passing the token via CLI argument rather than exporting it into a long-lived environment variable if that fits your security policy. 5) Note minor code issues (e.g., a reference to urllib.parse.quote in get_issues may require an import) — treat these as implementation bugs rather than malicious behavior. If the metadata remains inconsistent or you cannot verify the source, avoid using real credentials with this skill.

YouTrack

YouTrack integration for project management, time tracking, and knowledge base.

Quick Start

Authentication

To generate a permanent token:

1. From the main navigation menu, select Administration > Access Management > Users
2. Find your user and click to open settings
3. Generate a new permanent API token
4. Set the token as an environment variable:

export YOUTRACK_TOKEN=your-permanent-token-here

Important: Configure your hourly rate (default $100/hour) by passing --rate to invoice_generator.py or updating hourly_rate parameter in your code.

Then use any YouTrack script:

# List all projects
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-projects

# List issues in a project
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-issues "project: MyProject"

# Generate invoice for a project
python3 scripts/invoice_generator.py --url https://your-instance.youtrack.cloud --project MyProject --month "January 2026" --from-date "2026-01-01"

Python Scripts

scripts/youtrack_api.py

Core API client for all YouTrack operations.

In your Python code:

from youtrack_api import YouTrackAPI

api = YouTrackAPI('https://your-instance.youtrack.cloud', token='your-token')

# Projects
projects = api.get_projects()
project = api.get_project('project-id')

# Issues
issues = api.get_issues(query='project: MyProject')
issue = api.get_issue('issue-id')

# Create issue
api.create_issue('project-id', 'Summary', 'Description')

# Work items (time tracking)
work_items = api.get_work_items('issue-id')
issue_with_time = api.get_issue_with_work_items('issue-id')

# Knowledge base
articles = api.get_articles()
article = api.get_article('article-id')
api.create_article('project-id', 'Title', 'Content')

CLI usage:

python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud \
    --token YOUR_TOKEN \
    --list-projects

python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud \
    --get-issue ABC-123

python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud \
    --get-articles

scripts/invoice_generator.py

Generate client invoices from time tracking data.

In your Python code:

from youtrack_api import YouTrackAPI
from invoice_generator import InvoiceGenerator

api = YouTrackAPI('https://your-instance.youtrack.cloud', token='your-token')
generator = InvoiceGenerator(api, hourly_rate=100.0)

# Get time data for a project
project_data = generator.get_project_time_data('project-id', from_date='2026-01-01')

# Generate invoice
invoice_text = generator.generate_invoice_text(project_data, month='January 2026')
print(invoice_text)

CLI usage:

python3 scripts/invoice_generator.py \
    --url https://your-instance.youtrack.cloud \
    --project MyProject \
    --from-date 2026-01-01 \
    --month "January 2026" \
    --rate 100 \
    --format text

Save the text output and print to PDF for clients.

Common Workflows

1. List All Projects

python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-projects

2. Find Issues in a Project

# All issues in a project
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-issues "project: MyProject"

# Issues updated since a date
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-issues "project: MyProject updated >= 2026-01-01"

# Issues assigned to you
python3 scripts/youtrack_api.py --url https://your-instance.youtrack.cloud --list-issues "assignee: me"

3. Create a New Issue

from youtrack_api import YouTrackAPI

api = YouTrackAPI('https://your-instance.youtrack.cloud')
api.create_issue(
    project_id='MyProject',
    summary='Task title',
    description='Task description'
)

4. Generate Monthly Invoice

# Generate invoice for January 2026
python3 scripts/invoice_generator.py \
    --url https://your-instance.youtrack.cloud \
    --project ClientProject \
    --from-date 2026-01-01 \
    --month "January 2026" \
    --rate 100 \
    --format text > invoice.txt

Save the text output and print to PDF for clients.

5. Read Knowledge Base

from youtrack_api import YouTrackAPI

api = YouTrackAPI('https://your-instance.youtrack.cloud')

# All articles
articles = api.get_articles()

# Articles for specific project
articles = api.get_articles(project_id='MyProject')

# Get specific article
article = api.get_article('article-id')

Billing Logic

Invoice generator uses this calculation:

1. Sum all time tracked per issue (in minutes)
2. Convert to 30-minute increments (round up)
3. Minimum charge is 30 minutes (at configured rate/2)
4. Multiply by rate (default $100/hour = $50 per half-hour)

Examples:

• 15 minutes → $50 (30 min minimum)
• 35 minutes → $100 (rounded to 60 min)
• 60 minutes → $100
• 67 minutes → $150 (rounded to 90 min)

Environment Variables

• YOUTRACK_TOKEN: Your permanent API token (recommended over passing as argument)
• Set with export YOUTRACK_TOKEN=your-token

API Details

See REFERENCES.md for:

• Complete API endpoint documentation
• Query language examples
• Field IDs and structures

Error Handling

Scripts will raise errors for:

• Missing or invalid token
• Network issues
• API errors (404, 403, etc.)

Check stderr for error details.