@hailer/mcp 0.0.5 → 0.1.0

package/.claude/skills/MCP-publish-template-skill/SKILL.md

@@ -1,278 +0,0 @@
----
-name: Publish Template Skill
-description: Complete guide for publishing Hailer workspace templates to marketplace - use when creating shareable workflow configurations
----
-
-# Publish Template Skill
-
-This skill provides comprehensive documentation for publishing Hailer workspace templates to the marketplace. Templates allow you to share complete workspace configurations (workflows, fields, phases) with other workspaces.
-
-## When to Use This Skill
-
-Invoke this skill when:
-- Publishing a workspace as a template
-- Creating marketplace templates
-- Sharing workflow configurations with others
-- Managing template versions
-
-## What are Templates?
-
-**Templates = Shareable workspace configurations**
-
-Think of them as:
-- **Workspace Snapshots**: All workflows, fields, phases packaged together
-- **Reusable Blueprints**: Install in other workspaces
-- **Version Controlled**: Track changes across versions
-
-## Available Template Tools
-
-| Tool | Purpose |
-|------|---------|
-| `list_templates` | View templates in marketplace |
-| `create_template` | Create template entry |
-| `install_template` | Install template to workspace |
-| `get_template` | Get template details |
-| `publish_template` | Publish workspace as template |
-| `get_product` | Get product details (v3 API) |
-| `get_product_manifest` | Get product manifest |
-
-## Publishing a Template
-
-### Required Parameters
-
-```javascript
-publish_template({
-  title: "Template Name",           // Required: Display name (max 64 chars)
-  description: "What it does",      // Required: Description (max 4096 chars)
-  version: "1.0.0",                 // Required: Version string
-  versionDescription: "Release notes", // Required: Version notes
-  publisher: "Company Name",        // Required: Publisher name
-  iconFileId: "24-char-file-id"     // Required: Icon file ID
-})
-```
-
-### Optional Parameters
-
-```javascript
-{
-  productId: "existing-product-id",         // To UPDATE existing template
-  imageFileIds: ["file-id-1", "file-id-2"], // Preview images
-  externalUrl: "https://example.com"        // External website
-}
-```
-
-### Updating an Existing Template
-
-To update an existing template (change icon, description, etc.), include the `productId`:
-
-```javascript
-publish_template({
-  productId: "692d46bfca77093f10b0c09c",  // Existing product ID from list_templates
-  title: "Football Club Manager",
-  description: "Updated description",
-  version: "1.1.0",
-  versionDescription: "Updated icon and improved workflows",
-  publisher: "Community",
-  iconFileId: "new-icon-file-id"
-})
-```
-
-### Complete Workflow
-
-**Step 1: Gather ALL information from user**
-
-Use `AskUserQuestion` or direct questions to collect:
-- Template name (max 64 chars)
-- Description (what workflows are included)
-- Version (e.g., "1.0.0")
-- Version description (release notes)
-- Publisher name (company or person)
-- Icon source (URL, file path, or existing fileId)
-
-**Step 2: Upload the icon**
-
-**CRITICAL: Icons MUST be uploaded with `isPublic: true` or they won't display!**
-
-```javascript
-upload_files({ files: [{ path: "/path/to/icon.png", isPublic: true }] })
-// Returns: { fileId: "692d3e66e98c7bab4af7f0a1" }
-```
-
-**Step 3: Publish the template**
-```javascript
-publish_template({
-  title: "Football Manager",
-  description: "Complete football club management workspace",
-  version: "1.0.0",
-  versionDescription: "Initial release with Players, Matches, Training workflows",
-  publisher: "Hailer Oy",
-  iconFileId: "692d3e66e98c7bab4af7f0a1"
-})
-```
-
-### Interactive Icon Workflow
-
-When user asks to publish a template, use `AskUserQuestion` to ask about the icon:
-
-```javascript
-// Ask about icon
-AskUserQuestion({
-  questions: [{
-    question: "Template icon is required. How would you like to provide it?",
-    header: "Icon",
-    options: [
-      { label: "Upload from URL", description: "Provide a URL to an image" },
-      { label: "Upload from file path", description: "Provide a local file path" },
-      { label: "Use existing fileId", description: "I already have a file ID" }
-    ],
-    multiSelect: false
-  }]
-})
-```
-
-Then:
-- If URL: `upload_files({ files: [{ url: "https://...", isPublic: true }] })`
-- If path: `upload_files({ files: [{ path: "/path/to/icon.png", isPublic: true }] })`
-- If fileId: Use directly in `publish_template`
-
-**IMPORTANT:** Always use `isPublic: true` when uploading icons or they won't display in the UI!
-
-## What Gets Published
-
-When you publish a template, the **entire current workspace** is included:
-- All workflows
-- All fields and their configurations
-- All phases and their settings
-- Field relationships (activitylinks)
-- Function fields with formulas
-
-## Listing Templates
-
-```javascript
-// List private/workspace templates (default)
-list_templates()
-
-// List public marketplace templates
-list_templates({ publicOnly: true })
-```
-
-## Installing Templates
-
-```javascript
-install_template({
-  templateId: "692d3eade98c7bab4af7f173"
-})
-```
-
-This creates new workflows in your workspace based on the template.
-
-## Getting Template Details
-
-```javascript
-// Get template info
-get_template({ templateId: "692d3eade98c7bab4af7f173" })
-
-// Get product details (v3 API)
-get_product({ productId: "692d3eade98c7bab4af7f173" })
-
-// Get manifest
-get_product_manifest({ productId: "692d3eade98c7bab4af7f173" })
-```
-
-## API Flow (Internal)
-
-The `publish_template` tool performs two API calls:
-
-1. **v2.network.product.publishTemplate** - Creates template manifest
-   - Returns product ID
-
-2. **v3.product.create** - Publishes to marketplace
-   - Requires: `cid`, `targetId`, `name`, `description`, `type`, `publisher`, `icon`, `images`
-
-## PreToolUse Hook Protection
-
-A hook will **BLOCK** `publish_template` if any required field is missing:
-- title, description, version, versionDescription, publisher, iconFileId
-
-This ensures you gather ALL information before calling the tool.
-
-## Example: Full Publishing Flow
-
-```javascript
-// 1. User asks to publish template
-
-// 2. Gather ALL required information:
-//    - Ask for template name, description, version, release notes, publisher
-//    - Ask how to provide icon
-
-// 3. Upload icon if needed (MUST use isPublic: true!)
-const uploadResult = await upload_files({
-  files: [{ path: "/home/user/icons/football.png", isPublic: true }]
-});
-const iconFileId = uploadResult.fileIds[0];
-
-// 4. Publish template with ALL required fields
-const result = await publish_template({
-  title: "Football Manager",
-  description: "Complete football club management workspace with player tracking, match management, and statistics",
-  version: "1.0.0",
-  versionDescription: "Initial release with Players, Matches, Training workflows",
-  publisher: "Hailer Oy",
-  iconFileId: iconFileId
-});
-
-// 5. Share the product ID
-// Result includes productId for others to install
-```
-
-## Version Updates
-
-To update an existing template, include the `productId` parameter:
-
-```javascript
-// Get the product ID from list_templates first
-const templates = await list_templates();
-// Find your template's ID
-
-// Update with new version
-publish_template({
-  productId: "existing-product-id",
-  title: "Template Name",
-  description: "Updated description",
-  version: "1.1.0",  // New version number
-  versionDescription: "What changed in this version",
-  publisher: "Publisher Name",
-  iconFileId: "icon-file-id"
-})
-```
-
-## Requirements
-
-- User must be workspace administrator
-- Icon file must be uploaded first (24-char fileId required)
-- All required parameters must be provided
-
-## Common Errors
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| `"fileId" is required` | No icon provided | Upload icon first with `upload_files` |
-| `"images" is required` | Icon format wrong | Tool handles this automatically |
-| Permission denied | Not admin | User needs admin permissions |
-| Icon not displaying | File not public | Upload with `isPublic: true` |
-| Product not found | Wrong product ID | Use `list_templates` to get correct ID |
-
-## Best Practices
-
-1. **Use descriptive titles** - Clear names help users understand purpose
-2. **Write good descriptions** - Explain what workflows are included
-3. **Version semantically** - Use 1.0.0, 1.1.0, 2.0.0 format
-4. **Write release notes** - Document what changed in each version
-5. **Choose good icons** - Visual identity helps recognition
-
-## Related Tools
-
-- `list_workflows` - See workflows before publishing
-- `upload_files` - Upload template icon
-- `list_templates` - Verify template was published
-- `install_template` - Test by installing in another workspace