Update to Knock

{
  "name": "knock-cli",
  "description": "Guidelines for working with the Knock CLI to manage workflows, templates, and other notification resources in a Knock project.",
  "included_files": [
    {
      "relative_path": "rules/cli-commands-reference.md",
      "size_in_bytes": 18353
    },
    {
      "relative_path": "rules/cli-installation-authentication.md",
      "size_in_bytes": 5197
    },
    {
      "relative_path": "rules/guides-and-message-types.md",
      "size_in_bytes": 13797
    },
    {
      "relative_path": "rules/knock-directory-structure.md",
      "size_in_bytes": 8014
    },
    {
      "relative_path": "rules/partials.md",
      "size_in_bytes": 10434
    },
    {
      "relative_path": "rules/workflow-templates.md",
      "size_in_bytes": 27661
    }
  ],
  "skill_md_contents": "---\nname: knock-cli\ndescription: Guidelines for working with the Knock CLI to manage workflows, templates, and other notification resources in a Knock project.\n---\n\n# Knock CLI skill\n\nThis skill provides comprehensive guidelines for working with the Knock CLI to manage workflows, templates, and other notification resources.\n\n## Overview\n\nThe Knock CLI skill includes detailed rule sets covering:\n\n1. **CLI installation and authentication** - How to install and authenticate with the Knock CLI\n2. **Knock directory structure** - Understanding the knock directory layout and configuration\n3. **CLI commands reference** - Pull, push, and resource management commands\n4. **Workflow templates** - Structures, patterns, and best practices for workflows and templates\n5. **Guides and message types** - Working with in-app guides for lifecycle messaging and message types as their schema\n6. **Partials** - Reusable template building blocks for email design systems\n\n## How to use this skill\n\n### For initial setup\n\nWhen setting up a new project with Knock:\n\n1. **Start with installation and authentication** (`rules/cli-installation-authentication.md`)\n   - Verify the CLI is installed\n   - Authenticate with a service token or dashboard account\n   - Initialize the project with `knock init`\n\n2. **Understand the directory structure** (`rules/knock-directory-structure.md`)\n   - Learn the knock.json configuration\n   - Understand resource organization\n\n### For managing resources\n\nWhen working with Knock resources:\n\n1. **Use the CLI commands reference** (`rules/cli-commands-reference.md`)\n   - Pull resources from Knock to your local project\n   - Push changes back to Knock\n   - Work with specific resource types\n\n2. **Follow workflow and template guidelines** (`rules/workflow-templates.md`)\n   - Understand template modes and structures\n   - Avoid common mistakes with file paths and variables\n   - Follow best practices for workflow modifications\n\n### For managing guides and message types\n\nWhen working with in-app guides (banners, modals, announcements):\n\n1. **Start with guides and message types** (`rules/guides-and-message-types.md`)\n   - Understand that guides are separate from workflows (lifecycle messaging vs notifications)\n   - Message types define the schema; guides reference them via `schema_key` and `schema_variant_key`\n   - Use built-in types (banner, modal, card) when possible; create custom message types when needed\n\n2. **Discover before creating**\n   - Run `knock message-type list` to see available message type keys\n   - Run `knock guide list` to see existing guides\n   - Use exact keys from output when creating new guides\n\n### For working with partials\n\nWhen building reusable email components (callouts, quote blocks, comment cards):\n\n1. **Start with partials** (`rules/partials.md`)\n   - Understand partial file structure and `partial.json` schema\n   - Define `input_schema` for block editor fields (same format as message type variant fields)\n   - Use `visual_block_enabled: true` for partials that appear in the email visual block editor\n\n2. **Create and push**\n   - Run `knock partial new -k <key> -n \"Name\" -t html --force` to scaffold\n   - Add `input_schema` and edit content; validate and push with `knock partial push <key>`\n\n### For modifying workflows and templates\n\nWhen making changes to workflows or templates:\n\n1. **Always read before writing** - Understand existing structure before modifying\n2. **Use visual blocks for new emails** - Always default to visual blocks mode; only use HTML mode if explicitly requested\n3. **Use correct variable namespaces** - `data` for trigger payload, `vars` for environment variables\n4. **Verify file path references** - Paths are relative to the file containing the reference\n5. **Push after modifying** - Local file changes are not synced to Knock until you push. Run `knock workflow push <key>` (or the equivalent for other resource types) for changes to take effect.\n\n## Rule files reference\n\n- `rules/cli-installation-authentication.md` - Installation and authentication setup\n- `rules/knock-directory-structure.md` - Directory structure and configuration\n- `rules/cli-commands-reference.md` - CLI commands for resource management\n- `rules/workflow-templates.md` - Workflow and template structures and best practices\n- `rules/guides-and-message-types.md` - Guides and message types for lifecycle messaging\n- `rules/partials.md` - Partials and reusable template building blocks\n\n## Quick reference\n\n### Common commands\n\n```bash\n# Initialize a new project (interactive; use --knock-dir to skip prompts)\nknock init --knock-dir=./knock\n\n# Pull all resources from Knock (--force skips confirmation prompts)\nknock pull --all --force\n\n# Pull a specific workflow\nknock workflow pull <workflow-key> --force\n\n# Push all resources to Knock (push never prompts)\nknock push --all\n\n# Push a specific workflow\nknock workflow push <workflow-key>\n\n# Push a specific email layout\nknock layout push <layout-key>\n\n# List channels (discover valid channel_key values before creating workflows)\nknock channel list\n\n# Guide and message type commands\nknock message-type list          # Discover message type keys before creating guides\nknock guide list                 # List existing guides\nknock guide push <guide-key>     # Push a guide after modifying\nknock message-type push <key>    # Push a message type after modifying\n\n# Partial commands (email design system building blocks)\nknock partial list               # List existing partials\nknock partial new -k <key> -n \"Name\" -t html --force   # Create a new partial\nknock partial pull <key> --force # Pull a partial from Knock\nknock partial push <key>         # Push a partial after modifying\nknock partial validate <key>     # Validate a partial locally\n\n# Commit and promote a specific resource only (safe when other resources have pending changes)\nknock commit -m \"message\" --resource-type=workflow --resource-id=<key> --force\nknock commit list --resource-type=workflow --resource-id=<key>   # get the commit ID\nknock commit promote --only=<commit-id> --force\n```\n\n### Key concepts\n\n- **knockDir**: The directory where Knock resources are stored (configured in knock.json)\n- **Resource types**: workflows, email-layouts, guides, message-types, translations, partials, commits\n- **Guides vs workflows**: Guides are for lifecycle messaging (banners, modals); workflows are for notifications\n- **Template modes**: Visual blocks (default for new emails) vs HTML (only when explicitly requested)\n- **Variable namespaces**: `data` (trigger payload), `vars` (environment variables), `recipient`, `actor`, `tenant`\n\n### Important patterns\n\n1. **Use `--force` on commands with prompts** - Many CLI commands (pull, commit, promote, activate) display interactive confirmation prompts. Always pass `--force` to skip them in automated/agent contexts.\n2. **Push after every change** - Local edits stay local until pushed. No push = no update in Knock.\n3. **File path references use `@` suffix**: `\"content@\": \"visual_blocks/1.content.md\"`\n4. **Paths are relative to containing file**: Don't double the step directory\n5. **Always use `data.` for trigger payload values**, not `vars.`\n6. **Read existing files before modifying** to preserve structure\n7. **Discover channel keys before creating workflows** - Run `knock channel list` to get valid `channel_key` values\n8. **Discover message type keys before creating guides** - Run `knock message-type list` to get valid message type keys\n9. **Scope commits and promotes when working on a single resource** - `knock commit promote --to=<env>` promotes ALL unpromoted commits across all resources. When working on one resource, use `--resource-type` and `--resource-id` to commit only that resource, then use `knock commit promote --only=<commit-id>` to promote only that commit. See the \"Promote a specific resource only\" workflow below.\n\n## Best practices summary\n\n1. **Pull before editing** - Sync latest changes before making modifications\n2. **Push after modifying** - Local changes are not persisted to Knock until explicitly pushed\n3. **Read before writing** - Understand existing structure to avoid data loss\n4. **Use correct namespaces** - `data` for dynamic payload, `vars` for environment constants\n5. **Visual blocks by default** - Use visual blocks for new emails; preserve existing mode when editing\n6. **Verify paths** - File references are relative to the containing file\n7. **Test changes** - Validate workflows after pushing changes\n8. **Scope commits and promotes** - Default to `--resource-type`/`--resource-id` on commit and `--only` on promote when working on a single resource. Only use `knock commit promote --to=<env>` when you intend to promote all pending changes across every resource.\n"
}