@trendai-crem/claude-skills 0.1.0 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ npx @trendai-crem/claude-skills
 
 That's it. The command installs:
 
-1. **External skills** — [superpowers](https://github.com/obra/superpowers), [codex](https://github.com/oil-oil/codex)
+1. **External skills** — [superpowers](https://github.com/obra/superpowers))
 2. **Team skills** — custom skills maintained in this repo (override same-named externals)
 
 ## Update

package/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
 import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
-import { dirname } from 'path';
+import { dirname, join } from 'path';
 
 const __dir = dirname(fileURLToPath(import.meta.url));
 
@@ -44,3 +45,14 @@ const externalFailed = externalResults.filter(r => !r.ok);
 if (externalFailed.length > 0) {
   console.warn(`\nWARN: ${externalFailed.length} external source(s) failed — team skills installed successfully.`);
 }
+
+// Check for updates
+try {
+  const { version: current } = JSON.parse(readFileSync(join(__dir, 'package.json'), 'utf8'));
+  const res = await fetch('https://registry.npmjs.org/@trendai-crem/claude-skills/latest');
+  const { version: latest } = await res.json();
+  if (current !== latest) {
+    console.log(`\nUpdate available: ${current} → ${latest}`);
+    console.log(`Run: npx @trendai-crem/claude-skills@latest`);
+  }
+} catch { /* ignore update check failures */ }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@trendai-crem/claude-skills",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Claude Code skills installer for the trendai-crem team",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/daniel-tian_tmemu/claude-skills.git"
+    "url": "git+https://adc.github.trendmicro.com/CoreTech-SASEDL/claude-skills.git"
   },
   "bin": {
     "claude-skills": "cli.js"

package/skills/atlassian-tools/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: atlassian-tools
+description: |
+  Confluence wiki and Jira issue management. ALWAYS use this skill (not WebFetch)
+  for any atlassian.net URL, Confluence page, or Jira issue. Use for: wiki pages,
+  documentation, search/find wiki pages, retrieve wiki, create/update/delete pages,
+  Jira tickets, issues, bugs, sprints.
+allowed-tools: [Bash, Read, Write, Glob]
+metadata:
+  short-description: Confluence and Jira CLI tools with bidirectional sync
+  version: "1.5.1"
+  author: Hank Liao
+license: MIT
+---
+
+# Atlassian Tools
+
+## RULES (MUST FOLLOW)
+
+1. Run all commands from the skill directory (where this SKILL.md is located)
+2. ALWAYS use `-o <USER_CWD>/.atlassian` BEFORE the subcommand (not after)
+3. Replace `<USER_CWD>` with the user's working directory (where they invoked the skill)
+4. **UPDATE WORKFLOW: Always check local storage first before updating**
+   - Before updating any wiki page or Jira issue, check if it exists in local storage
+   - If found locally: Edit the local `.md` file, then use `update --file` with that file
+   - If not found locally: First `retrieve`/`get` it, then edit the local file, then update
+   - **NEVER use inline `-d` or description arguments when a local file exists**
+
+Correct: `uv run python confluence_cli.py -o /user/project/.atlassian retrieve 123456`
+Wrong: `uv run python confluence_cli.py retrieve 123456 -o /path` (will fail)
+
+## TRIGGERS (When to Use This Skill)
+
+ALWAYS use this skill (never WebFetch) when you see:
+- URLs containing `atlassian.net` or `/wiki/`
+- Jira issue keys like `PROJ-123`
+- Keywords: Confluence, wiki, Jira, Atlassian, ticket, issue
+
+User intent mapping:
+- "get/download/retrieve wiki/page" → `confluence_cli.py retrieve`
+- "get all child pages" → `confluence_cli.py retrieve -r`
+- "search/find wiki pages" → `confluence_cli.py search`
+- "create wiki page" → `confluence_cli.py create`
+- "update/edit wiki" → **check local first**, then `confluence_cli.py update --file`
+- "get issue/ticket" → `jira_cli.py get`
+- "get epic with children" → `jira_cli.py get -r`
+- "create ticket/issue" → `jira_cli.py create`
+- "update issue" → **check local first**, then `jira_cli.py update --description-file`
+- "add comment" → `jira_cli.py comment`
+- "change status" → `jira_cli.py transition`
+
+## UPDATE WORKFLOW (CRITICAL)
+
+**Always prefer editing local files over inline arguments.** This ensures content integrity and proper version tracking.
+
+### Confluence Page Update
+
+1. **Check local storage**: `ls <USER_CWD>/.atlassian/confluence/pages/`
+2. **If page exists locally**:
+   - Read: `<USER_CWD>/.atlassian/confluence/pages/<page-title>/<page-title>.md`
+   - Edit the markdown file with requested changes
+   - Update: `confluence_cli.py update <page_id> --file <USER_CWD>/.atlassian/confluence/pages/<page-title>/<page-title>.md`
+3. **If page NOT found locally**:
+   - First retrieve: `confluence_cli.py retrieve <page_id_or_url>`
+   - Then follow step 2 (page will now exist at `<USER_CWD>/.atlassian/confluence/pages/<page-title>/`)
+
+### Jira Issue Update
+
+1. **Check local storage**: `ls <USER_CWD>/.atlassian/jira/issues/`
+2. **If issue exists locally**:
+   - Read: `<USER_CWD>/.atlassian/jira/issues/<ISSUE-KEY>/description.md`
+   - Edit the markdown file with requested changes
+   - Update: `jira_cli.py update <ISSUE-KEY> --description-file <USER_CWD>/.atlassian/jira/issues/<ISSUE-KEY>/description.md`
+3. **If issue NOT found locally**:
+   - First retrieve: `jira_cli.py get <issue_key>`
+   - Then follow step 2 (issue will now exist at `<USER_CWD>/.atlassian/jira/issues/<ISSUE-KEY>/`)
+
+### Why This Matters
+
+- Preserves full document context (macros, formatting, images)
+- Enables accurate incremental edits
+- Maintains sync between local cache and remote
+- Avoids data loss from partial inline updates
+
+## CONFLUENCE CLI
+
+Base: `uv run python confluence_cli.py -o <USER_CWD>/.atlassian <command>`
+
+### Commands
+
+**retrieve** `<page_id_or_url>` `[-r]` `[-f]`
+Download page to local storage. Accepts page ID or full URL.
+- `-r` recursive (include all child pages)
+- `-f` force re-fetch even if cached
+
+**create** `<file>` `-s <space_key>` `[-t <title>]` `[-p <parent_id>]` `[-f markdown|html]`
+Create new page from .md or .html file.
+- `-s` space key (required, or set CONFLUENCE_SPACE_KEY env var)
+- `-t` page title (defaults to filename)
+- `-p` parent page ID (for subpages)
+- `-f` force format (auto-detected from extension)
+
+**update** `<page_id>` `--file <file>` `[-t <title>]` `[-m <message>]` `[-f markdown|html]`
+Update existing page. Auto-syncs local cache after update.
+- `--file` source file with new content
+- `-t` new title
+- `-m` version message
+- `-f` force format
+
+**sync** `[<page_id>]` `[--all]` — Fetch latest from remote to local cache
+- `<page_id>` page ID or URL (required unless --all is used)
+- `--all` sync all locally cached pages
+**list** — List locally cached pages
+**info** `<page_id>` — Show local page metadata
+**delete** `<page_id>` — Remove from local storage only
+**delete-from-confluence** `<page_id>` `[--local-only]` — Delete from Confluence (and local)
+**storage** — Show storage stats
+
+**search** `<query>` `[--limit N]` `[--space KEY]` `[--cursor TOKEN]` `[--retrieve N]` `[--json]`
+Search Confluence pages by keyword using CQL full-text search.
+- `<query>` search text (required)
+- `--limit` results per page (1-50, default: 10)
+- `--space` filter by space key (e.g., DEV, DOCS)
+- `--cursor` pagination cursor from previous search
+- `--retrieve` auto-retrieve top N results to local storage (1-20)
+- `--json` output JSON format instead of table
+
+### Examples
+
+```bash
+# Get page by URL
+uv run python confluence_cli.py -o /project/.atlassian retrieve "https://domain.atlassian.net/wiki/spaces/SPACE/pages/123456"
+
+# Get page and all children
+uv run python confluence_cli.py -o /project/.atlassian retrieve 123456 -r
+
+# Create page from markdown
+uv run python confluence_cli.py -o /project/.atlassian create doc.md -s DDIT -t "API Docs"
+
+# Create subpage
+uv run python confluence_cli.py -o /project/.atlassian create doc.md -s DDIT -t "API Docs" -p 789012
+
+# Update page (preferred: edit local file first)
+# 1. Check if exists: ls /project/.atlassian/confluence/pages/
+# 2. Edit the local markdown file
+# 3. Update from file:
+uv run python confluence_cli.py -o /project/.atlassian update 123456 --file /project/.atlassian/confluence/pages/API-Docs/API-Docs.md -m "Fixed typos"
+
+# Sync all cached pages with latest from Confluence
+uv run python confluence_cli.py -o /project/.atlassian sync --all
+
+# Search for pages containing "OAuth"
+uv run python confluence_cli.py -o /project/.atlassian search "OAuth"
+
+# Search with limit and space filter
+uv run python confluence_cli.py -o /project/.atlassian search "API documentation" --limit 20 --space DEV
+
+# Search and auto-retrieve top 3 results
+uv run python confluence_cli.py -o /project/.atlassian search "deployment guide" --retrieve 3
+
+# Search with JSON output for scripting
+uv run python confluence_cli.py -o /project/.atlassian search "testing" --json
+```
+
+## JIRA CLI
+
+Base: `uv run python jira_cli.py -o <USER_CWD>/.atlassian <command>`
+
+### Commands
+
+**get** `<issue_key>` `[-r]` `[-f]`
+Download issue to local storage.
+- `-r` recursive (include all child issues)
+- `-f` force re-fetch even if cached
+
+**create** `<project>` `<type>` `<summary>` `[-d <desc>]` `[--description-file <file>]` `[--parent <key>]` `[-p <priority>]` `[-l <labels>]` `[--no-sprint]`
+Create new issue. Auto-saves to local storage. Auto-adds to sprint and applies default labels if configured.
+- `<project>` project key (e.g., PROJ)
+- `<type>` issue type (Task, Bug, Story, Epic)
+- `<summary>` issue title
+- `-d` description text
+- `--description-file` markdown file for description
+- `--parent` parent issue key
+- `-p` priority (Highest, High, Medium, Low, Lowest)
+- `-l` comma-separated labels (merged with JIRA_DEFAULT_LABELS)
+- `--no-sprint` skip auto-adding to sprint
+
+**update** `<issue_key>` `[-s <summary>]` `[-d <desc>]` `[--description-file <file>]` `[-p <priority>]` `[-l <labels>]`
+Update issue fields. Auto-syncs local cache.
+- `--description-file` markdown file for description (**preferred over -d**)
+
+**comment** `<issue_key>` `<text>` — Add comment. Auto-syncs local cache.
+
+**transition** `<issue_key>` `<status>` — Change status (e.g., "In Progress", "Done"). Auto-syncs local cache.
+
+**assign-to-me** `<issue_key>` — Assign to current user. Auto-syncs local cache.
+
+**set-parent** `<issue_key>` `[parent_key]` `[--clear]` — Set or clear parent relationship
+
+**search** `<jql>` `[-l <limit>]` — Search with JQL query
+- `-l` max results (default 50)
+
+**types** `<project>` — List available issue types for project
+
+**add-to-sprint** `<issue_keys>` `[-s <sprint_name>]` `[-p <project>]`
+Add issues to a sprint.
+- `<issue_keys>` comma-separated issue keys (e.g., PROJ-1,PROJ-2)
+- `-s` sprint name (uses JIRA_SPRINT_NAME_PATTERN if not specified)
+- `-p` project key (defaults to JIRA_PROJECT_KEY)
+
+**add-label** `<issue_keys>` `<labels>`
+Add labels to multiple issues.
+- `<issue_keys>` comma-separated issue keys
+- `<labels>` comma-separated labels to add
+
+**delete-issue** `<issue_key>` — Delete from Jira (and local if present)
+**list** — List locally cached issues
+**info** `<issue_key>` — Show local issue details
+**sync** `[<issue_key>]` `[--all]` — Fetch latest from remote
+- `<issue_key>` issue key (required unless --all is used)
+- `--all` sync all locally cached issues
+**delete** `<issue_key>` — Remove from local storage only
+**storage** — Show storage stats
+
+### Examples
+
+```bash
+# Get single issue
+uv run python jira_cli.py -o /project/.atlassian get PROJ-123
+
+# Get epic with all children
+uv run python jira_cli.py -o /project/.atlassian get PROJ-100 -r
+
+# Create task
+uv run python jira_cli.py create PROJ Task "Implement feature" -d "Description here"
+
+# Create from spec file
+uv run python jira_cli.py create PROJ Story "User auth" --description-file spec.md --parent PROJ-100
+
+# Update issue (preferred: edit local file first)
+# 1. Check if exists: ls /project/.atlassian/jira/issues/PROJ-123/
+# 2. Edit: /project/.atlassian/jira/issues/PROJ-123/description.md
+# 3. Update from file:
+uv run python jira_cli.py -o /project/.atlassian update PROJ-123 --description-file /project/.atlassian/jira/issues/PROJ-123/description.md
+
+# Update issue (simple field changes only)
+uv run python jira_cli.py -o /project/.atlassian update PROJ-123 -s "New title" -p High
+
+# Add comment
+uv run python jira_cli.py comment PROJ-123 "Fixed in commit abc123"
+
+# Change status
+uv run python jira_cli.py transition PROJ-123 "In Progress"
+
+# Search
+uv run python jira_cli.py search "project = PROJ AND status = 'To Do'" -l 20
+
+# Sync all cached issues with latest from Jira
+uv run python jira_cli.py -o /project/.atlassian sync --all
+```
+
+## REFERENCE
+
+### Format Support
+- Input: Markdown (.md) or HTML (.html), auto-detected by extension
+- Output: Pages saved as both .html and .md
+- Supported: headings, lists, tables, code blocks, links, bold/italic, Mermaid diagrams
+
+### Confluence Macros & Elements
+
+**Fully Converted (lossless round-trip):**
+- Code blocks → markdown fenced blocks (```language)
+- Mermaid diagrams → ```mermaid blocks
+- Status macros → `<!-- status: TITLE ;; colour: COLOR -->`
+- Jira macros → `<!-- jira: KEY ;; server: NAME ;; serverId: ID -->`
+- Expand macros → `<details data-confluence-expand="true"><summary>Title</summary>content</details>`
+- User mentions → `<!-- @user:ACCOUNT_ID -->`
+- Page links → `<!-- @page:SPACE|TITLE|DISPLAY_TEXT -->`
+- Emoticons → `<!-- @emoji:NAME|ID|SHORTNAME -->`
+- Images → `<!-- confluence-image filename: NAME ac:width: N ... -->`
+
+**Preserved as Comments:**
+- TOC, Children, Info, Warning, Note, and other macros
+- Format: `<!-- confluence-macro: toc\nstyle: none\ncontent:\n-->`
+
+**Special Handling:**
+- Pipe characters in link text auto-escaped for markdown table compatibility
+- Code blocks inside expand macros preserved and restored
+
+### Storage Structure
+
+```text
+<USER_CWD>/.atlassian/
+├── confluence/pages/<page-title>/
+│   ├── metadata.json
+│   ├── <page-title>.html
+│   └── <page-title>.md
+└── jira/issues/<ISSUE-KEY>/
+    ├── metadata.json
+    ├── full_data.json
+    └── description.md
+```
+
+Recursive retrieval creates nested folders for parent/child relationships.
+
+### Credentials
+
+Configure in `~/.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "ATLASSIAN_DOMAIN": "trendmicro.atlassian.net",
+    "ATLASSIAN_EMAIL": "your-email@trendmicro.com",
+    "ATLASSIAN_API_TOKEN": "your_api_token",
+    "CONFLUENCE_SPACE_KEY": "MYSPACE",
+    "JIRA_PROJECT_KEY": "PROJ",
+    "JIRA_SPRINT_NAME_PATTERN": "📜 TLC Sprint *",
+    "JIRA_DEFAULT_LABELS": "tpa,backend"
+  }
+}
+```
+
+Get API token: <https://id.atlassian.com/manage-profile/security/api-tokens>
+
+## Version History
+
+### v1.5.0 (2025-12-24)
+- **Enhanced**: Lossless round-trip conversion for Confluence elements
+  - Status macros (with colour parameter)
+  - Jira issue macros (with server/serverId)
+  - Expand/collapse macros (full content preservation)
+  - User mentions (@user)
+  - Page links (cross-space supported)
+  - Emoticons (with emoji-id and shortname)
+  - Image attachments (all attributes preserved)
+- **Fixed**: Pipe characters in link text breaking markdown tables
+- **Fixed**: Code blocks inside expand macros now properly restored
+- **Fixed**: Image restoration pattern for single-line format
+
+### v1.4.0 (2025-12-23)
+- **Added**: `search` command for Confluence pages using CQL full-text search
+  - Search by keyword with ranked results
+  - Pagination support via `--cursor`
+  - Filter by space with `--space`
+  - Auto-retrieve top N results with `--retrieve`
+  - JSON output format with `--json`
+
+### v1.3.0 (2025-12-22)
+- **Added**: `--all` flag to `sync` command for batch operations
+
+### v1.2.0
+- **Added**: Project-level storage with configurable `-o` flag
+- **Added**: Hierarchical Jira issue storage
+
+### v1.1.0
+- **Added**: Recursive page retrieval with `-r` flag
+- **Added**: HTML/Markdown conversion with macro preservation
+
+### v1.0.0
+- Initial release with Confluence and Jira CLI tools