git:20251125.5b56c8e to git:20251125.e6e3982

- 1. **jira-mcp**: MCP server communication for all Jira API operations

- **Key Principle**: All Jira content (descriptions, comments) MUST use Jira wiki markup syntax, NOT Markdown. This is enforced by the jira-syntax skill and consumed by the jira-mcp skill.

- ### Project Structure (v2.0.1+)

- │ ├── jira-mcp/ # MCP communication skill (~130 lines SKILL.md)

- │ │ ├── SKILL.md # Lean entry point with trigger descriptions

- │ │ ├── jql-reference.md # JQL syntax and examples (with TOC)

- │ │ ├── mcp-tools-guide.md # Complete MCP tool documentation

- │ │ └── workflow-patterns.md # Common operation sequences

- │ └── jira-syntax/ # Syntax validation skill (~80 lines SKILL.md)

- │ ├── SKILL.md # Lean entry point with trigger descriptions

- │ │ ├── bug-report-template.md

- │ │ └── feature-request-template.md

- │ │ └── jira-syntax-quick-reference.md # Complete syntax (with TOC)

- │ └── validate-jira-syntax.sh

- │ └── plugin.json # Plugin metadata with skills array

- ├── archive/

- │ └── jira-unified/ # Old v1.x unified skill (archived)

- ├── README.md # User-facing documentation

- ├── CHANGELOG.md # Version history

- └── MIGRATION.md # Upgrade instructions

- ### Skill Separation Rationale

- **Why Two Skills?**

- 1. **Separation of Concerns**: API operations (jira-mcp) vs syntax enforcement (jira-syntax)

- 2. **Independent Activation**: Skills activate based on context (MCP operations vs formatting)

- 3. **Offline Capability**: jira-syntax works offline for validation without MCP server

- 4. **Modularity**: Clear boundaries between API communication and content formatting

- ### Core Components

- **jira-mcp Skill** (`skills/jira-mcp/SKILL.md`):

- * **SKILL.md**: Lean entry point (~130 lines) with comprehensive trigger description

- * **Description triggers**: JQL queries, issue creation/updates, comments, worklogs, transitions, linking, batch operations, sprint/board operations

- * **References**: JQL syntax (with TOC), MCP tools guide, workflow patterns

- **jira-syntax Skill** (`skills/jira-syntax/SKILL.md`):

- * **SKILL.md**: Lean entry point (~80 lines) with comprehensive trigger description

- * **Description triggers**: Wiki markup formatting, Markdown-to-Jira conversion, templates, syntax validation, h2./h3. headings, {code:lang} blocks

- * **Templates**: Bug reports, feature requests

- * **References**: Complete Jira syntax documentation (with TOC)

- * **Scripts**: Automated syntax validation

- **Plugin Configuration** (`.claude-plugin/plugin.json`):

- * `skills` array declaring both skills with paths

- * MCP server configuration for mcp-atlassian

- * Plugin metadata and versioning

- ### SKILL.md Best Practices

- Based on skill-creator framework guidelines:

- 1. **Valid Frontmatter Fields**: Only `name` and `description` (NOT version, mcp_servers)

- 2. **Description as Trigger**: Include "when to use" information in description field for proper skill activation

- 3. **Lean Body**: Keep SKILL.md body concise (<500 lines), pointing to reference files

- 4. **Progressive Disclosure**: Metadata (~100 words) → SKILL.md body → References (unlimited)

- 5. **Reference TOCs**: Add Table of Contents to reference files >100 lines

- 6. **No Duplication**: Don't repeat reference content in SKILL.md body

- ## Development Workflow

- 1. **Validate Syntax**: Ensure all Jira wiki markup in templates follows official standards

- 3. **Update Checklist**: Templates include validation checklists - keep them current

- 4. **Preserve Structure**: Templates follow established section patterns (h2. for main, h3. for sub)

- 5. **Update References**: Keep `jira-syntax-quick-reference.md` comprehensive and accurate

-

- ### When Modifying jira-mcp Skill

-

- 1. **MCP Tool Usage**: New features should leverage mcp-atlassian tools correctly

- 2. **Update References**: Maintain `jql-reference.md`, `mcp-tools-guide.md`, `workflow-patterns.md`

- 3. **Test MCP Operations**: Verify tool calls work against real Jira instance

- 4. **Document Workflows**: Add new patterns to workflow-patterns.md

-

- ### When Updating Documentation

-

- 1. **README.md**: User-facing documentation with installation and usage examples

- 2. **SKILL.md files**: Technical reference for skill activation (update both as needed)

- 3. **MIGRATION.md**: Document breaking changes and upgrade paths

- 4. **plugin.json**: Update version numbers following SemVer

-

- ## MCP Server Integration

-

- This skill **bundles its own MCP configuration** via `.mcp.json` - users do not need to manually configure the mcp-atlassian server.

- ### Automatic MCP Configuration

- The skill includes `.mcp.json` which automatically configures the mcp-atlassian server using Docker:

- ```json

- {

- "mcp-atlassian": {

- "command": "docker",

- "args": ["run", "--rm", "-i", "--pull=always", "--env-file", "${JIRA_ENV_FILE}",

- "ghcr.io/sooperset/mcp-atlassian:latest"],

- "env": {

- "JIRA_ENV_FILE": "${HOME}/.env.jira"

- }

- }

- }

-

- **Key Point**: No manual MCP server configuration required - the skill handles this automatically.

-

- ### User Setup Requirements

-

- Users only need to create `~/.env.jira` with their credentials:

- * `JIRA_URL` - Jira instance URL (e.g., `https://company.atlassian.net`)

- * `JIRA_USERNAME` - User email (Cloud) or username (Server/DC)

- * `JIRA_API_TOKEN` - API token or Personal Access Token

-

- ### Available MCP Tools

-

- All tools use the prefix `mcp__mcp-atlassian__jira_*` :

- * **Read**: `get_issue`, `search`, `get_project_issues`, `get_transitions`, `get_worklog`

- * **Write**: `create_issue`, `batch_create_issues`, `update_issue`, `add_comment`, `add_worklog`, `transition_issue`

- * **Link**: `create_issue_link`, `link_to_epic`, `remove_issue_link`

- * **Attachments**: `download_attachments`

- ## Testing and Validation

- ### Syntax Validation

- # Validate Jira syntax in a file or string

- ./skills/jira-syntax/scripts/validate-jira-syntax.sh <file_or_text>

- ### Manual Testing Workflow

-

- 1. Ensure `~/.env.jira` is configured with valid credentials

- 2. Use the skill - MCP server starts automatically via `.mcp.json`

- 3. Test MCP tool calls through Claude Code

- 4. Verify formatting renders correctly in Jira web interface

- 5. Validate syntax using validation script

-

- ## Marketplace Integration

-

- This skill is part of the Netresearch Claude Code Marketplace.

-

- ### Plugin Metadata

-

- `.claude-plugin/plugin.json` defines marketplace properties:

- * name, version, description

- * category, keywords

- * author information

-

- File needs to follow plugin schema: <https://code.claude.com/docs/en/plugins-reference#plugin-manifest-schema>

- ### Version Management

- Version follows SemVer format in `plugin.json`:

- ```json

- {

- "version": "2.0.1"

- }

- ```

- **Note**: Version is managed ONLY in `plugin.json`, NOT in SKILL.md frontmatter. SKILL.md frontmatter should only contain `name` and `description`.

- 2. **MCP Dependency**: Skill requires mcp-atlassian to be configured

- 3. **Template Fidelity**: Templates must match Jira's expected structure

- 4. **Documentation Accuracy**: Syntax references must align with official Jira docs

- * mcp-atlassian GitHub: <https://github.com/sooperset/mcp-atlassian>