OpenSkillIndex← back to search
claude-code

Clawhub-skills backlog-agent

Manage projects on Nulab Backlog — issues, wikis, milestones, Git, sprints for Japan's top PM tool

install
source · Clone the upstream repo
git clone https://github.com/traygerbig/clawhub-skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/traygerbig/clawhub-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/business-ops-pack/backlog-agent" ~/.claude/skills/traygerbig-clawhub-skills-backlog-agent && rm -rf "$T"
manifest: business-ops-pack/backlog-agent/SKILL.md
source content
╔═══════════════════════════════════════════════════╗
║  ┌───────────────────────────────────────────┐    ║
║  │  B A C K L O G   A G E N T               │    ║
║  │     ━━━━━━━━━━━━━━━━━━━━━━                │    ║
║  │  📋 Issues → Wiki → Git → Sprints        │    ║
║  │     Nulab Project Management CLI          │    ║
║  └───────────────────────────────────────────┘    ║
╚═══════════════════════════════════════════════════╝


backlog
nulab
project-management
issue-tracker
git-hosting

Author Version License PM API

Command your entire project from the terminal -- create issues, track sprints, update wikis, and manage Git repos on Japan's most trusted project management platform.

Overview

Backlog Agent delivers full programmatic control over Nulab Backlog, the project management platform trusted by development teams, agencies, and enterprises across Japan and Asia-Pacific. Backlog uniquely combines issue tracking, wiki documentation, Git/SVN repository hosting, and Gantt chart planning in a single integrated platform -- a combination that has made it the go-to tool for Japanese software teams who need everything in one place without the fragmentation of using Jira plus Confluence plus GitHub plus separate Gantt tools. This skill makes every Backlog operation accessible from your terminal, enabling seamless integration into development workflows, CI/CD pipelines, and automated reporting systems.

The agent covers the complete Backlog feature set through its comprehensive REST API v2: issue lifecycle management with custom fields, statuses, priorities, and resolution tracking; wiki page creation and editing with Markdown and Backlog's native markup support; milestone and version management for release planning; sprint board operations for agile teams; Git repository management including branches, pull requests, and webhooks; file attachment handling; notification configuration; and bulk operations for project-wide changes. The agent understands Backlog's project key convention (e.g., 

PROJ-123
) and translates between human-readable references and internal IDs seamlessly. It also supports cross-project operations for organizations managing multiple simultaneous projects -- a common pattern in Japanese IT consulting firms (SIer) managing client portfolios.

Architecture:

  ┌──────────────────────────────────────────────────────────────┐
  │                     Backlog Agent CLI                         │
  │                                                              │
  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐   │
  │  │  Issues  │ │   Wiki   │ │   Git    │ │    Sprint     │   │
  │  │  Engine  │ │  Manager │ │  Bridge  │ │    Board      │   │
  │  └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬────────┘   │
  │       │            │            │               │            │
  │  ┌────▼────────────▼────────────▼───────────────▼──────────┐ │
  │  │        Project Key Resolver & ID Mapper                 │ │
  │  │     (PROJ-123 ↔ internal IDs, cross-project)            │ │
  │  └──────────────────────┬──────────────────────────────────┘ │
  │                         │                                    │
  │  ┌──────────────────────▼──────────────────────────────────┐ │
  │  │         API Key / OAuth2 Auth Layer                     │ │
  │  │    ({space}.backlog.com or {space}.backlog.jp)           │ │
  │  └──────────────────────┬──────────────────────────────────┘ │
  └─────────────────────────┼────────────────────────────────────┘
                            │ HTTPS
                            ▼
               ┌──────────────────────────┐
               │  {space}.backlog.com/api  │
               │    Backlog REST API v2    │
               └──────────────────────────┘

System Prompt Instructions

You are the Backlog Agent, a project management automation specialist for Nulab Backlog. Follow these rules precisely:

  1. Authenticate using API key (
    apiKey
    query parameter) by default. Support OAuth2 for user-context operations. Never embed API keys in log output.
  2. All API requests target 
    https://{BACKLOG_SPACE_ID}.backlog.com/api/v2/
    or 
    https://{BACKLOG_SPACE_ID}.backlog.jp/api/v2/
    . Auto-detect the correct domain based on space configuration.
  3. Issue keys follow the 
    {PROJECT_KEY}-{NUMBER}
    convention (e.g., 
    DEV-42
    ). Always resolve project keys and issue numbers to internal numeric IDs before making API calls. Display keys in human-readable format in output.
  4. Support all issue fields: 
    issueType
    , 
    priority
    (High/Medium/Low), 
    status
    (Open/In Progress/Resolved/Closed), 
    assignee
    , 
    category
    , 
    version
    , 
    milestone
    , 
    startDate
    , 
    dueDate
    , 
    estimatedHours
    , 
    actualHours
    , 
    resolution
    , and custom fields.
  5. When creating issues, validate that the specified issue type, priority, and assignee exist in the target project. Provide helpful suggestions on mismatch.
  6. Wiki pages use Backlog's native markup format by default. Support Markdown when the project has Markdown enabled. Auto-detect the project's wiki format setting.
  7. Git operations proxy through the Backlog API, not direct Git protocol. Support branch listing, pull request creation and review, and webhook management.
  8. Pull requests require: 
    summary
    , 
    description
    , 
    base
    branch, 
    branch
    (source), and optionally 
    assigneeId
    and 
    issueId
    (to link to an issue).
  9. Milestone operations must respect the project's milestone list. Auto-suggest existing milestones when creating issues. Milestones have 
    startDate
    , 
    releaseDueDate
    , and optional 
    description
    .
  10. Sprint board operations map to Backlog's "Board" feature. Issues move between statuses on the board. Track velocity by summing estimated hours across sprint milestones.
  11. File attachments upload to the space's shared storage first (
    /api/v2/space/attachment
    ), returning an 
    id
    that can then be linked to issues, wiki pages, or pull requests.
  12. Bulk operations use individual API calls (Backlog has no native bulk endpoint). The agent batches these with concurrency control and progress reporting. Maximum recommended: 100 operations per batch.
  13. Notification preferences: respect the user's notification settings. Do not trigger excessive notifications during bulk operations -- use the 
    notifiedUserId
    parameter selectively.
  14. Custom fields are project-scoped. Fetch the project's custom field definitions before validating create/update payloads. Support types: Text, TextArea, Numeric, Date, SingleList, MultipleList, CheckBox, RadioButton.
  15. Cross-project queries use the 
    /api/v2/issues
    endpoint with 
    projectId
    array. Always scope queries to specific projects unless the user explicitly requests space-wide search.
  16. Gantt chart data is derived from issue start dates and due dates. When generating reports, validate that issues have both dates set. Warn about issues missing scheduling data.
  17. Rate limiting: Backlog allows varying limits based on plan (Free: 60/min, Standard: 300/min, Premium: 600/min). Detect the plan from the space info endpoint and configure accordingly.
  18. Handle Backlog's webhook events for CI/CD integration. Support event types: issue creation/update, wiki update, Git push, pull request, and file upload.
  19. Always display timestamps in the project's configured timezone. Default to JST (Asia/Tokyo) for Japanese spaces.

Environment Variables

VariableRequiredDefaultDescription
BACKLOG_SPACE_ID
Yes-Your Backlog space identifier (e.g., 
myteam
for 
myteam.backlog.com
)
BACKLOG_API_KEY
Yes-API key from Personal Settings > API in Backlog
BACKLOG_PROJECT_KEY
No-Default project key (e.g., 
DEV
) used when 
--project
is omitted
BACKLOG_DOMAIN
No
backlog.com
Domain suffix: 
backlog.com
(international) or 
backlog.jp
(Japan)
BACKLOG_OUTPUT_FORMAT
No
table
Default output format: 
table
, 
json
, 
csv
BACKLOG_CONCURRENCY
No
3
Maximum concurrent API calls for bulk operations
BACKLOG_TIMEZONE
No
Asia/Tokyo
Timezone for displaying timestamps

Commands

bl issues

List issues with filtering.

$ bl issues --project DEV --status "In Progress" --assignee me

  Key       Type     Priority  Summary                          Assignee     Due Date     Updated
  ────────  ───────  ────────  ───────────────────────────────  ───────────  ───────────  ──────────
  DEV-142   Task     High      API認証モジュールのリファクタ     石原 達也     2026-03-07   2h ago
  DEV-138   Bug      High      ログイン時のCSRFトークンエラー    石原 達也     2026-03-05   5h ago
  DEV-135   Task     Medium    CI/CDパイプライン最適化           石原 達也     2026-03-10   1d ago
  DEV-131   Feature  Medium    ダッシュボード通知機能追加        石原 達也     2026-03-15   2d ago
  DEV-127   Task     Low       ドキュメント英語化対応            石原 達也     2026-03-20   3d ago

  Showing 5 issues (In Progress, assigned to 石原 達也) in project DEV


bl create

Create a new issue.

$ bl create --project DEV --type Bug --priority High \
    --summary "本番環境でのメモリリーク検出" \
    --description "Production server memory usage increasing 2%/hour since deploy v2.3.1. GC logs show unreleased connections in ConnectionPool." \
    --assignee ishihara --milestone "v2.3.2" --due "2026-03-05"

  Issue created successfully
  Key:         DEV-143
  Type:        Bug
  Priority:    High
  Summary:     本番環境でのメモリリーク検出
  Assignee:    石原 達也
  Milestone:   v2.3.2
  Due Date:    2026-03-05
  Status:      Open
  Created:     2026-03-01 11:42:18 JST
  URL:         https://myteam.backlog.com/view/DEV-143


bl update

Update an existing issue.

$ bl update DEV-143 --status "In Progress" --actual-hours 2.5 \
    --comment "Root cause identified: connection pool not closing idle connections. Fix in PR #89."

  Issue updated successfully
  Key:         DEV-143
  Changes:
    Status:        Open → In Progress
    Actual Hours:  0 → 2.5h
  Comment:     Added (ID: 45678)
  Updated:     2026-03-01 14:15:33 JST
  URL:         https://myteam.backlog.com/view/DEV-143


bl wiki

Create and manage wiki pages.

$ bl wiki --project DEV --list

  Page ID   Title                              Updated By     Updated        Tags
  ────────  ─────────────────────────────────  ─────────────  ─────────────  ──────────────
  W-001     プロジェクト概要                    石原 達也      2026-02-28     overview
  W-002     開発環境セットアップ手順            佐藤 花子      2026-02-25     setup, dev
  W-003     API設計ガイドライン                 田中 太郎      2026-02-20     api, design
  W-004     デプロイ手順書                      石原 達也      2026-03-01     deploy, ops
  W-005     障害対応フロー                      山田 次郎      2026-02-15     incident

  Total: 5 wiki pages in project DEV


bl milestone

Manage project milestones and versions.

$ bl milestone --project DEV

  Name       Start Date   Release Due   Issues   Progress   Status
  ─────────  ───────────  ────────────  ───────  ─────────  ────────
  v2.3.0     2026-01-15   2026-02-15    28/28    100%       Released
  v2.3.1     2026-02-01   2026-02-28    24/24    100%       Released
  v2.3.2     2026-03-01   2026-03-15    8/18     44%        Active
  v2.4.0     2026-03-15   2026-04-30    0/32     0%         Planned

  Active: v2.3.2 (10 open issues, 8 closed, target: 2026-03-15)


bl sprint

View and manage sprint boards.

$ bl sprint --project DEV --current

  Sprint: v2.3.2 Sprint 1 (2026-03-01 → 2026-03-15)

  ┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐
  │  Open (3)       │  In Progress(5) │  Resolved (6)   │  Closed (4)     │
  ├─────────────────┼─────────────────┼─────────────────┼─────────────────┤
  │  DEV-140 [M]    │  DEV-142 [H]    │  DEV-130 [H]    │  DEV-125 [M]    │
  │  デプロイ自動化  │  API認証リファ   │  DB最適化        │  UIテスト追加    │
  │                 │                 │                 │                 │
  │  DEV-139 [L]    │  DEV-138 [H]    │  DEV-129 [M]    │  DEV-124 [L]    │
  │  コード整理      │  CSRFバグ修正   │  キャッシュ導入   │  README更新     │
  │                 │                 │                 │                 │
  │  DEV-137 [M]    │  DEV-135 [M]    │  DEV-128 [M]    │  DEV-123 [M]    │
  │  E2Eテスト      │  CI/CD最適化     │  ログ集約        │  依存関係更新    │
  │                 │                 │                 │                 │
  │                 │  DEV-131 [M]    │  DEV-126 [H]    │  DEV-122 [H]    │
  │                 │  通知機能追加    │  セキュリティ    │  認証バグ修正    │
  │                 │                 │                 │                 │
  │                 │  DEV-127 [L]    │  DEV-133 [L]    │                 │
  │                 │  ドキュメント    │  型定義整理      │                 │
  │                 │                 │                 │                 │
  │                 │                 │  DEV-134 [M]    │                 │
  │                 │                 │  APIテスト       │                 │
  └─────────────────┴─────────────────┴─────────────────┴─────────────────┘

  Velocity: 42h estimated | 28h completed | Burndown: 56% at day 1/14


bl git

Manage Git repositories and pull requests.

$ bl git --project DEV --repos

  Repository     Default Branch  Last Push        Commits  PRs Open
  ─────────────  ──────────────  ───────────────  ───────  ────────
  dev-api        main            2026-03-01 10:22  1,842    3
  dev-frontend   main            2026-03-01 09:45  2,156    2
  dev-infra      main            2026-02-28 18:30  487      0

  Total: 3 repositories | 5 open pull requests

$ bl git --project DEV --repo dev-api --prs

  PR #    Title                              Author       Base    Branch          Status
  ─────  ───────────────────────────────────  ───────────  ──────  ──────────────  ────────
  #89    Fix connection pool memory leak      石原 達也     main    fix/mem-leak    Open
  #88    Add rate limiting middleware          佐藤 花子     main    feat/rate-limit Review
  #87    Update dependency versions            田中 太郎     main    chore/deps      Merged


bl search

Search across issues, wiki, and comments.

$ bl search "memory leak" --project DEV --scope issues,wiki

  Issues (3 matches):
  DEV-143  [Bug/High]     本番環境でのメモリリーク検出        In Progress
  DEV-098  [Bug/Medium]   ステージングメモリリーク調査         Closed
  DEV-055  [Task/Low]     メモリプロファイリングツール導入     Closed

  Wiki (1 match):
  W-005  障害対応フロー  Section: "メモリリーク発生時の対応手順"

  Total: 4 results across issues and wiki


bl report

Generate project status reports.

$ bl report --project DEV --type weekly

  Weekly Report: DEV (2026-02-24 → 2026-03-01)

  Summary:
    Issues Created:    12
    Issues Closed:     8
    Issues In Review:  4
    Avg Resolution:    3.2 days

  By Priority:
    High:    3 created / 2 closed
    Medium:  7 created / 5 closed
    Low:     2 created / 1 closed

  By Assignee:
    石原 達也     4 closed (16.5h actual)
    佐藤 花子     2 closed (8.0h actual)
    田中 太郎     1 closed (4.5h actual)
    山田 次郎     1 closed (3.0h actual)

  Milestone Progress:
    v2.3.2: 44% (8/18 issues closed, 7 days remaining)

  Blockers:
    DEV-143 [High] Memory leak in production — needs immediate attention


bl bulk

Perform bulk operations on issues.

$ bl bulk --project DEV --action update --query "milestone:v2.3.1 AND status:Resolved" \
    --set '{"status": "Closed", "resolution": "Fixed"}'

  Bulk update preview:
  Project:    DEV
  Matching:   12 issues
  Action:     Set status → Closed, resolution → Fixed

  Proceed? [y/N]: y

  Processing: [████████████████████████████████████████] 12/12

  Bulk update complete
  Updated:    12 issues
  Failed:     0
  Duration:   4.8 seconds

  Affected:   DEV-112, DEV-113, DEV-114, DEV-115, DEV-116, DEV-117,
              DEV-118, DEV-119, DEV-120, DEV-121, DEV-122, DEV-124

Workflow

  Developer                  Backlog Agent                 Backlog API
  ─────────                  ─────────────                 ───────────
      │                            │                            │
      │  bl create --project DEV   │                            │
      │  --type Bug --priority H   │                            │
      ├───────────────────────────►│                            │
      │                            │  Resolve project key → ID  │
      │                            │  Validate issue type       │
      │                            │  Validate assignee         │
      │                            │  Resolve milestone name    │
      │                            │                            │
      │                            │  POST /api/v2/issues       │
      │                            ├───────────────────────────►│
      │                            │  201 {id, issueKey, ...}   │
      │                            │◄───────────────────────────┤
      │  DEV-143 created           │  Map IDs → readable keys   │
      │◄───────────────────────────┤                            │
      │                            │                            │
      │  bl update DEV-143         │                            │
      │  --status "In Progress"    │                            │
      ├───────────────────────────►│                            │
      │                            │  Resolve DEV-143 → ID      │
      │                            │  Map status → statusId     │
      │                            │  PATCH /api/v2/issues/{id} │
      │                            ├───────────────────────────►│
      │                            │  200 OK                    │
      │                            │◄───────────────────────────┤
      │  DEV-143 updated           │                            │
      │◄───────────────────────────┤                            │
      │                            │                            │
      │  bl sprint --current       │                            │
      ├───────────────────────────►│  GET milestones, issues    │
      │                            ├───────────────────────────►│
      │                            │◄───────────────────────────┤
      │  Sprint board rendered     │  Group by status           │
      │◄───────────────────────────┤  Calculate velocity        │
      │                            │                            │

Error Handling

ErrorCauseSolution
401 Unauthorized: Authentication failed
API key is invalid, expired, or not setRegenerate your API key at Personal Settings > API in Backlog. Verify 
BACKLOG_API_KEY
is correctly set.
404 Not Found: Project not found
Project key is invalid or you do not have accessVerify the project key with 
bl issues --list-projects
. Ensure your account has been added to the project.
400 Invalid issue type
The specified issue type does not exist in this projectEach project defines its own issue types. Use 
bl issues --project KEY --types
to list valid types for the project.
400 Duplicate issue key
Attempting to create an issue with a key that already existsIssue keys are auto-generated. This error typically indicates a race condition. Retry the creation.
403 Forbidden: Insufficient privileges
Your role does not permit this operation (e.g., guest trying to delete)Contact the project admin to upgrade your role. Guests have read-only access by default.
413 File too large
Attachment exceeds the space's file size limit (varies by plan)Free plan: 100MB total storage. Compress files or use external storage with links. Check 
bl status
for storage usage.
429 Rate Limit Exceeded
Too many requests for your plan tierAgent automatically backs off. Free: 60/min, Standard: 300/min, Premium: 600/min. Use 
--concurrency 1
for conservative mode.

FAQ

1. How do I get a Backlog API key? Log in to Backlog, go to Personal Settings > API > Register new API key. Copy the key and set it as 

BACKLOG_API_KEY
.

2. What is the difference between 

backlog.com
and 
backlog.jp
? 
backlog.jp
is the legacy Japanese domain. 
backlog.com
is the current international domain. Both work identically. Set 
BACKLOG_DOMAIN
to match your space's domain.

3. Can I create issues across multiple projects in one command? Yes, use 

bl create --project DEV,QA,OPS --type Task --summary "Quarterly review"
to create the same issue template across projects.

4. How do I link issues to Git pull requests? Include the issue key in the PR description or use 

bl git --pr-create --issue DEV-143
. Backlog automatically links PRs that reference issue keys in commit messages.

5. Can I export Gantt chart data? Yes. 

bl report --project DEV --type gantt --format csv
exports all issues with start/due dates suitable for external Gantt tools. Include 
--include-subtasks
for work breakdown structures.

6. How do sprint boards work in Backlog? Sprints map to milestones with date ranges. 

bl sprint --current
shows issues grouped by status for the active milestone. Velocity is calculated from estimated vs actual hours.

7. Can I manage multiple spaces from one CLI? Yes. Use 

--space other-team
to override 
BACKLOG_SPACE_ID
per command, or maintain multiple config profiles in 
~/.backlog-agent/config.yaml
.

8. How do I bulk-import issues from CSV? Use 

bl bulk --import ./issues.csv --project DEV
. The CSV must include columns matching field names (Summary, Type, Priority, Assignee, etc.). The agent validates all rows before importing.

9. Does the agent support Backlog's webhook events? Yes. 

bl webhook --create --project DEV --url https://ci.jenkins-server.local/webhook/backlog --events issue_created,git_pushed
configures event notifications for CI/CD integration.

10. Can I track time spent on issues? Yes. Use 

bl update DEV-143 --actual-hours 4.5
to log time. 
bl report --project DEV --type timesheet --period 2026-03
generates timesheet reports grouped by assignee.

11. How do I manage wiki page attachments? Upload: 

bl wiki --project DEV --page W-001 --attach ./diagram.png
. The file is uploaded to shared storage and linked to the wiki page.

12. What markup formats does the wiki support? Backlog supports its own markup and Markdown (project setting). The agent auto-detects the format. Use 

--format markdown
or 
--format backlog
to force a specific format.

Data Storage

The Backlog Agent maintains local state for efficient operations:

~/.backlog-agent/
├── config.yaml                # Space, API key, default project settings
├── cache/
│   ├── spaces/
│   │   └── myteam.json        # Space info cache (TTL: 1 hour)
│   ├── projects/
│   │   ├── DEV.json           # Project metadata cache (TTL: 15 min)
│   │   ├── DEV_types.json     # Issue types cache (TTL: 1 hour)
│   │   ├── DEV_statuses.json  # Status list cache (TTL: 1 hour)
│   │   └── DEV_members.json   # Member list cache (TTL: 15 min)
│   └── recent_issues.json     # Recently accessed issues (TTL: 5 min)
├── templates/
│   ├── bug_report.json        # Issue creation templates
│   ├── feature_request.json
│   └── weekly_report.md       # Report generation templates
├── logs/
│   ├── api-2026-03.log        # Monthly API log (keys redacted)
│   ├── bulk_operations.log    # Bulk operation audit trail
│   └── errors.log             # Error details with context
└── exports/
    └── DEV_report_20260301.csv  # Generated reports (auto-cleanup: 30 days)

Project metadata and type definitions are cached aggressively since they change infrequently, dramatically reducing API calls during interactive sessions. Issue caches use short TTLs to ensure data freshness. All API keys are redacted from logs.

Comparison

FeatureBacklog AgentJira CLIGitHub CLILinear CLIRedmine CLI
Japanese UI/docsNative (JP + EN)Plugin requiredEN onlyEN onlyPlugin
Issue trackingFull CRUD + custom fieldsFull CRUDIssues onlyFull CRUDFull CRUD
Wiki built-inYes (native)Confluence (separate)No (use repo)NoYes
Git hostingBuilt-inBitbucket (separate)NativeNoPlugin
Gantt chartsNativePlugin/CloudNoCyclesPlugin
Sprint boardsMilestone-basedScrum/KanbanProjectsCyclesPlugin
File storagePer-space quotaUnlimited (Cloud)LFSNoPer-project
Pull requestsBuilt-inBitbucketNativeNoNo
Cross-project searchYesJQLLimitedYesYes
Pricing (small team)Free (10 users)Free (10 users)Free (unlimited)Free (250 issues)Free (OSS)
Target marketJapan / APACGlobalGlobal (developers)StartupsSelf-hosted