Command Creator

This skill provides a complete walkthrough for creating reusable commands via the Packmind CLI.

About Commands

Commands are structured, multi-step workflows that capture repeatable tasks, recipes, and automation patterns. They help teams standardize common development workflows and enable Claude to execute complex tasks consistently.

What Commands Provide

1. Multi-step workflows - Structured sequences of actions to accomplish a task
2. Context validation - Checkpoints to ensure requirements are met before execution
3. When-to-use guidance - Clear scenarios describing when the command is applicable
4. Code snippets - Optional examples demonstrating each step's implementation

Command Playbook Structure

Every command playbook is a JSON file with this structure:

{
  "name": "Command Name",
  "summary": "What the command does, why it's useful, and when it's relevant",
  "whenToUse": [
    "Scenario 1 when this command applies",
    "Scenario 2 when this command applies"
  ],
  "contextValidationCheckpoints": [
    "Question 1 to validate before proceeding?",
    "Question 2 to ensure context is clear?"
  ],
  "steps": [
    {
      "name": "Step Name",
      "description": "What this step does and how to implement it",
      "codeSnippet": "```typescript\n// Optional code example\n```"
    }
  ]
}

Validation Requirements

The CLI validates playbooks automatically. Requirements:

• name: Non-empty string
• summary: Non-empty string describing intent, value, and relevance
• whenToUse: Array with at least one scenario (non-empty strings)
• contextValidationCheckpoints: Array with at least one checkpoint (non-empty strings)
• steps: Array with at least one step
• steps[].name: Non-empty string (step title)
• steps[].description: Non-empty string (implementation details)
• steps[].codeSnippet (optional): Code example wrapped in markdown code fences with language identifier (e.g., ```typescript\n...code...\n```)

Prerequisites

Packmind CLI

Check if packmind-cli is installed:

packmind-cli --version

If not available, install it:

npm install -g @packmind/cli

Then login to Packmind:

packmind-cli login

Command Creation Process

Step 1: Understanding the Command's Purpose

Skip this step only when the command's workflow and steps are already clearly defined.

To create an effective command, clearly understand:

1. What workflow does this command automate?

   • Example: "Setting up a new API endpoint with tests"
   • Example: "Creating a new React component with proper structure"

2. When should this command be triggered?

   • Specific scenarios (e.g., "When adding a new feature")
   • Specific contexts (e.g., "After creating a domain entity")

Example clarifying questions:

• "What multi-step workflow do you want to automate?"
• "What scenarios should trigger this command?"
• "What context needs to be validated before running this workflow?"

Step 2: Designing the Workflow

Transform the understanding from Step 1 into concrete steps.

Step Writing Guidelines

1. Clear name - Use a concise title (e.g., "Setup Dependencies", "Create Test File")
2. Actionable description - Explain what to do and how to implement it
3. One concept per step - Focus on a single action
4. Optional code snippet - Include when it clarifies the implementation

Good descriptions:

• "Create a new file at `src/components/{ComponentName}.tsx` with the basic component structure including props interface and default export"

Bad descriptions:

• "Create file" (too vague)

Context Validation Checkpoints

Questions that verify requirements before execution:

Good checkpoints:

• "Is the component name and location specified?"
• "Are the API endpoint requirements (method, path, payload) defined?"

Bad checkpoints:

• "Ready to start?" (doesn't validate anything)

When-To-Use Scenarios

Define specific, actionable scenarios:

Good scenarios:

• "When adding a new REST endpoint to the API"
• "After creating a new domain entity that needs persistence"

Bad scenarios:

• "When coding" (too broad)

Step 3: Creating the Playbook File

1. Create a draft JSON file in .packmind/commands/_drafts/ (create the folder if missing) using filename <command-slug>-draft.json (lowercase with hyphens)
2. Structure the playbook with all required fields documented above

Example minimal playbook:

{
  "name": "Create API Endpoint",
  "summary": "Set up a new REST API endpoint with controller, service, and tests.",
  "whenToUse": ["When adding a new REST endpoint to the API"],
  "contextValidationCheckpoints": ["Is the HTTP method and path defined?"],
  "steps": [
    {
      "name": "Create Controller",
      "description": "Create the controller file in \`infra/http/controllers/\` with the endpoint handler."
    }
  ]
}

Step 4: Review Before Submission

Before running the CLI command, you MUST get explicit user approval:

1. Show the user the complete playbook content in a formatted preview:

   • Name
   • Summary
   • When to use scenarios
   • Context validation checkpoints
   • Each step with name, description, and code snippet (if any)

2. Provide the file path to the draft JSON file (.packmind/commands/_drafts/<command-slug>-draft.json) so users can open and edit it directly if needed.

3. Ask: "Here is the command that will be created on Packmind. The draft file is at `<path>` if you want to review or edit it. Do you approve?"

4. Wait for explicit user confirmation before proceeding to Step 5.

5. If the user requests changes, edit the draft file and re-submit for approval.

Step 5: Creating the Command via CLI

Run the packmind-cli command to create the command:

packmind-cli commands create <path-to-playbook.json> --origin-skill=create-command

Example:

packmind-cli commands create ./.packmind/commands/_drafts/create-api-endpoint-draft.json --origin-skill=create-command

Expected output on success:

packmind-cli Command "Your Command Name" created successfully (ID: <uuid>)
View it in the webapp: <url>

Troubleshooting

"Not logged in" error:

packmind-cli login

"Failed to resolve global space" error:

• Verify your API key is valid
• Check network connectivity to Packmind server

JSON validation errors:

• Ensure all required fields are present
• Verify JSON syntax is valid (use a JSON validator)
• Check that all arrays have at least one entry

Step 6: Cleanup

After the command is successfully created, delete the temporary files:

1. Delete the draft JSON file in .packmind/commands/_drafts/ (e.g., <command-slug>-draft.json)

Only clean up on success - if the CLI command fails, keep the files so the user can retry.

Step 7: Offer to Add to Package

After successful creation, check if the command fits an existing package:

1. Run packmind-cli install --list to get available packages
2. If no packages exist, skip this step silently and end the workflow
3. Analyze the created command's name and summary against each package's name and description
4. If a package is a clear semantic fit (the command's domain/technology aligns with the package's purpose):
   • Present to user: "This command seems to fit the <package-slug> package."
   • Offer three options:
     • Add to <package-slug>
     • Choose a different package
     • Skip
5. If no clear fit is found, skip silently (do not mention packages)
6. If user chooses to add:
   • Run: packmind-cli packages add --to <package-slug> --command <command-slug> --origin-skill=create-command
   • Ask: "Would you like me to run packmind-cli install to sync the changes?"
   • If yes, run: packmind-cli install

Complete Example

Here's a complete example creating a command for setting up a new API endpoint:

File: create-api-endpoint.command.playbook.json

{
  "name": "Create API Endpoint",
  "summary": "Set up a new REST API endpoint with controller, service, and tests following the hexagonal architecture pattern.",
  "whenToUse": [
    "When adding a new REST endpoint to the API",
    "When implementing a new backend feature that exposes HTTP endpoints"
  ],
  "contextValidationCheckpoints": [
    "Is the HTTP method and path defined (e.g., POST /users)?",
    "Is the request/response payload structure specified?",
    "Is the associated use case or business logic identified?"
  ],
  "steps": [
    {
      "name": "Create Controller",
      "description": "Create the controller file in the \`infra/http/controllers/\` directory with the endpoint handler and input validation.",
      "codeSnippet": "```typescript\n@Controller('users')\nexport class UsersController {\n  @Post()\n  async create(@Body() dto: CreateUserDTO) {\n    return this.useCase.execute(dto);\n  }\n}\n```"
    },
    {
      "name": "Create Use Case",
      "description": "Create the use case in the \`application/useCases/\` directory implementing the business logic."
    },
    {
      "name": "Create Tests",
      "description": "Create unit tests for the controller and use case in their respective \`.spec.ts\` files following the Arrange-Act-Assert pattern."
    },
    {
      "name": "Register in Module",
      "description": "Add the controller and use case to the appropriate NestJS module's \`controllers\` and \`providers\` arrays."
    }
  ]
}

Creating the command:

packmind-cli commands create ./.packmind/commands/_drafts/create-api-endpoint-draft.json --origin-skill=create-command

Quick Reference