@atlashub/smartstack-cli 1.37.0 → 2.0.0

package/templates/skills/cc-skill/references/best-practices.md

@@ -0,0 +1,167 @@
+# Skill Best Practices
+
+Based on official Claude Code documentation and SmartStack conventions.
+
+## Design Principles
+
+### 1. Keep SKILL.md Under 500 Lines
+- Move detailed content to `references/` directory
+- Move code templates to `templates/` directory
+- Use progressive step loading for complex workflows
+- Each step file should also be focused (< 200 lines ideal)
+
+### 2. Write Clear Descriptions
+- Use natural language keywords Claude can match against
+- Include "Use this skill when:" trigger list
+- Be specific about what the skill does AND does not do
+
+```yaml
+# Good
+description: |
+  Generate API controllers following REST conventions.
+  Use this skill when:
+  - Creating new API endpoints
+  - Adding CRUD operations to a module
+  - Generating controller tests
+
+# Bad
+description: Controller generation
+```
+
+### 3. Set Invocation Mode Correctly
+
+| Scenario | Setting |
+|----------|---------|
+| Research, analysis, exploration | `disable-model-invocation: false` |
+| Code generation, scaffolding | `disable-model-invocation: false` |
+| Deployment, publishing | `disable-model-invocation: true` |
+| Git operations (commit, push) | `disable-model-invocation: true` |
+| Database operations (reset, seed) | `disable-model-invocation: true` |
+| Destructive operations | `disable-model-invocation: true` |
+
+**Rule of thumb:** If the skill has side effects that can't be easily undone, set `disable-model-invocation: true`.
+
+### 4. Use Progressive Step Loading for Complex Workflows
+- Minimizes context usage (only current step loaded)
+- State persists across steps via conversation
+- Each step is self-contained and testable
+- Easier to maintain and debug
+
+### 5. Prefer Forked Context for Research
+- Clean context = no interference from previous conversation
+- Ideal for exploration, search, analysis
+- Fast agents (haiku) for simple searches
+- Full agents (sonnet/opus) for complex reasoning
+
+## Structural Best Practices
+
+### Directory Organization
+```
+my-skill/
+├── SKILL.md           # Main definition (< 500 lines)
+├── steps/             # Progressive step files
+│   ├── step-00-init.md
+│   └── step-01-*.md
+├── templates/         # Code templates for generation
+├── references/        # Documentation and checklists
+├── scripts/           # Executable scripts
+└── examples/          # Example outputs
+```
+
+### Step File Convention
+- Always start with `step-00-init.md` for initialization
+- Number sequentially: step-00, step-01, step-02, ...
+- Use descriptive names: step-01-analyze, step-02-generate
+- Each step defines `next_step` in frontmatter (except last)
+- Last step handles completion summary
+
+### Frontmatter Minimalism
+Only include fields that differ from defaults:
+```yaml
+# Good - minimal, clear
+---
+name: my-skill
+description: What it does
+disable-model-invocation: true
+---
+
+# Bad - redundant defaults
+---
+name: my-skill
+description: What it does
+disable-model-invocation: true
+user-invocable: true        # This is the default
+model: inherit              # This is the default
+context:                    # Empty, not needed
+---
+```
+
+## Content Best Practices
+
+### 1. Use XML Sections Consistently
+Standard order: objective → quick_start → parameters → workflow → state_variables → entry_point → step_files → execution_rules → success_criteria
+
+### 2. Provide Usage Examples
+Always include `<quick_start>` with realistic examples:
+```xml
+<quick_start>
+` ` `bash
+/my-skill basic-usage
+/my-skill --flag advanced-usage
+/my-skill subcommand arg1 arg2
+` ` `
+</quick_start>
+```
+
+### 3. Document State Variables
+For progressive skills, always document what persists:
+```xml
+<state_variables>
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{name}` | string | Required - item name |
+| `{auto}` | boolean | Optional - skip prompts |
+</state_variables>
+```
+
+### 4. Define Clear Success Criteria
+What does "done" look like?
+```xml
+<success_criteria>
+- Files generated at correct paths
+- No validation errors
+- Build passes (if applicable)
+- User informed of next steps
+</success_criteria>
+```
+
+### 5. Use Compact Output
+Prefer tables over prose for summaries:
+```markdown
+| Metric | Value |
+|--------|-------|
+| Files created | 5 |
+| Lines generated | 342 |
+| Warnings | 0 |
+| Status | Complete |
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why | Better |
+|-------------|-----|--------|
+| Huge SKILL.md (> 500 lines) | Wastes context | Split into steps + references |
+| Vague description | Claude can't auto-invoke | Use trigger keywords |
+| Missing entry_point | Steps won't load | Always define entry_point |
+| Circular step refs | Infinite loop | Linear step chain |
+| Hardcoded paths | Not portable | Use relative paths |
+| No success criteria | Unclear completion | Define measurable criteria |
+| Skipping validation step | Quality issues | Always validate at end |
+
+## Testing Your Skill
+
+1. **Manual test:** Run `/my-skill` with various arguments
+2. **Edge cases:** Test with missing args, invalid input, empty state
+3. **Audit:** Run `/cc-audit` to validate structure
+4. **Step chain:** Verify each step loads the next correctly
+5. **Cross-project:** Test in different project contexts if applicable

package/templates/skills/cc-skill/references/frontmatter-reference.md

@@ -0,0 +1,182 @@
+# Skill Frontmatter Reference
+
+Complete reference for all SKILL.md YAML frontmatter fields, based on the official Claude Code documentation.
+
+Source: https://code.claude.com/docs/en/skills
+
+## Required Fields
+
+### `name`
+- **Type:** string
+- **Required:** YES
+- **Constraints:** lowercase, max 64 characters, kebab-case
+- **Purpose:** Unique identifier. Becomes the `/name` command.
+- **Examples:**
+  ```yaml
+  name: my-skill
+  name: code-review
+  name: deploy-staging
+  ```
+
+### `description`
+- **Type:** string (multi-line supported)
+- **Required:** YES
+- **Purpose:** Claude uses this to decide when to auto-invoke the skill. Include trigger keywords.
+- **Examples:**
+  ```yaml
+  description: Generate API controllers following REST conventions.
+
+  description: |
+    Deploy application to staging environment.
+    Use this skill when:
+    - User mentions "deploy", "staging", "release"
+    - User wants to push changes to staging
+    - Deployment pipeline needs to be triggered
+  ```
+
+## Optional Fields
+
+### `disable-model-invocation`
+- **Type:** boolean
+- **Default:** false
+- **Purpose:** When `true`, only the user can invoke via `/name`. Claude will never auto-invoke.
+- **Use for:** Side-effect operations (deploy, commit, publish, delete)
+- **Example:**
+  ```yaml
+  disable-model-invocation: true
+  ```
+
+### `user-invocable`
+- **Type:** boolean
+- **Default:** true
+- **Purpose:** When `false`, skill is hidden from /menu. Used for background knowledge injection.
+- **Example:**
+  ```yaml
+  user-invocable: false
+  ```
+
+### `allowed-tools`
+- **Type:** string (comma-separated)
+- **Default:** (none)
+- **Purpose:** Tools the skill can use without triggering permission prompts.
+- **Valid tools:** Read, Write, Edit, Bash, Glob, Grep, Task, WebFetch, WebSearch, NotebookEdit, AskUserQuestion, TodoWrite, Skill, ToolSearch
+- **Example:**
+  ```yaml
+  allowed-tools: "Read, Grep, Glob, WebSearch, WebFetch"
+  ```
+
+### `model`
+- **Type:** string
+- **Default:** inherit
+- **Valid values:** inherit, sonnet, opus, haiku
+- **Purpose:** Override the model used when this skill runs.
+- **Guidance:**
+  - `haiku` - Fast, cheap. Simple tasks.
+  - `sonnet` - Balanced. Most tasks.
+  - `opus` - Most capable. Complex reasoning.
+  - `inherit` - Use user's configured model.
+- **Example:**
+  ```yaml
+  model: haiku
+  ```
+
+### `context`
+- **Type:** string
+- **Valid values:** fork
+- **Purpose:** Run skill in an isolated subagent context. Separate conversation, clean state.
+- **Example:**
+  ```yaml
+  context: fork
+  ```
+
+### `agent`
+- **Type:** string
+- **Purpose:** Which subagent type to use when `context: fork`.
+- **Valid values:** Explore, Plan, general-purpose, Bash, or any custom agent name
+- **Example:**
+  ```yaml
+  context: fork
+  agent: Explore
+  ```
+
+### `argument-hint`
+- **Type:** string
+- **Purpose:** Autocomplete hint shown in the /menu.
+- **Example:**
+  ```yaml
+  argument-hint: "<command> [options]"
+  argument-hint: "[filename]"
+  argument-hint: "<create|update> [name]"
+  ```
+
+### `hooks`
+- **Type:** object
+- **Purpose:** Lifecycle hooks scoped to this skill.
+- **Events:** PreToolUse, PostToolUse, Stop, SessionStart, etc.
+- **Example:**
+  ```yaml
+  hooks:
+    PreToolUse:
+      - matcher: "Bash"
+        hooks:
+          - type: command
+            command: "./scripts/validate.sh"
+  ```
+
+## Dynamic Placeholders
+
+Available in SKILL.md content (not frontmatter):
+
+| Placeholder | Description |
+|-------------|-------------|
+| `$ARGUMENTS` | All arguments passed to skill |
+| `$1`, `$2`, ... | Positional arguments |
+| `$ARGUMENTS[0]` | Same as $1 |
+| `${CLAUDE_SESSION_ID}` | Current session ID |
+| `` !`command` `` | Run shell command, inject output |
+
+## Examples
+
+### Minimal Skill
+```yaml
+---
+name: hello
+description: Greet the user
+---
+
+Say hello to the user: $ARGUMENTS
+```
+
+### Side-Effect Skill
+```yaml
+---
+name: deploy
+description: Deploy to staging
+disable-model-invocation: true
+argument-hint: "[environment]"
+---
+```
+
+### Research Skill
+```yaml
+---
+name: search-code
+description: Search codebase for patterns
+context: fork
+agent: Explore
+allowed-tools: "Read, Grep, Glob"
+argument-hint: "<query>"
+---
+```
+
+### Complex Workflow
+```yaml
+---
+name: generate-api
+description: |
+  Generate API endpoints. Use when:
+  - Creating new API routes
+  - Adding CRUD operations
+argument-hint: "<entity> [--with-tests]"
+---
+```

package/templates/skills/cc-skill/references/skill-patterns.md

@@ -0,0 +1,199 @@
+# Skill Patterns Reference
+
+Common patterns used in Claude Code skills.
+
+## Pattern 1: Subcommands
+
+Route to different behaviors based on first argument. Used by: efcore, gitflow.
+
+```yaml
+---
+name: my-tool
+description: Multi-command tool
+argument-hint: "<command> [options]"
+disable-model-invocation: true
+---
+
+<quick_start>
+` ` `bash
+/my-tool status
+/my-tool create
+/my-tool deploy
+` ` `
+</quick_start>
+
+<parameters>
+<subcommands>
+| Command | Description |
+|---------|-------------|
+| `status` | Show current status |
+| `create` | Create new item |
+| `deploy` | Deploy to environment |
+</subcommands>
+</parameters>
+
+<entry_point>
+**ROUTING LOGIC:**
+1. Parse command from input
+2. Route to command-specific step:
+
+| Command | Route To |
+|---------|----------|
+| `status` | `steps/status/step-00-init.md` |
+| `create` | `steps/create/step-00-init.md` |
+| `deploy` | `steps/deploy/step-00-init.md` |
+</entry_point>
+```
+
+## Pattern 2: Flags (Enable/Disable)
+
+Toggle behavior with flags. Used by: controller.
+
+```yaml
+<parameters>
+<flags>
+**Enable flags (lowercase):**
+| Short | Long | Description |
+|-------|------|-------------|
+| `-a` | `--auto` | Skip confirmations |
+| `-v` | `--verbose` | Detailed output |
+
+**Disable flags (UPPERCASE):**
+| Short | Long | Description |
+|-------|------|-------------|
+| `-A` | `--no-auto` | Disable auto mode |
+| `-V` | `--no-verbose` | Disable verbose |
+</flags>
+</parameters>
+```
+
+Parsing in step-00-init:
+```
+Enable flags (lowercase - turn ON):
+  -a or --auto    → {auto_mode} = true
+  -v or --verbose → {verbose} = true
+
+Disable flags (UPPERCASE - turn OFF):
+  -A or --no-auto    → {auto_mode} = false
+  -V or --no-verbose → {verbose} = false
+```
+
+## Pattern 3: Dynamic Context Injection
+
+Inject runtime information into skill content. Used by: efcore.
+
+```yaml
+---
+name: my-skill
+description: Skill with runtime context
+---
+
+## Current state (auto-injected)
+- Branch: !`git branch --show-current`
+- Files: !`ls -la src/ | head -10`
+- Version: !`node -p "require('./package.json').version"`
+```
+
+The `` !`command` `` syntax runs the command before skill content is sent to Claude.
+
+## Pattern 4: Argument Placeholders
+
+Access user arguments in skill content.
+
+```markdown
+## Task
+Process the following: $ARGUMENTS
+
+## Specific arguments
+First arg: $1
+Second arg: $2
+All args: $ARGUMENTS
+```
+
+## Pattern 5: XML-Style Sections
+
+Structure skill content with XML tags. Standard sections:
+
+| Section | Purpose | When to use |
+|---------|---------|-------------|
+| `<objective>` | One-paragraph purpose statement | Always |
+| `<quick_start>` | Usage examples | Always |
+| `<parameters>` | Flags, subcommands, parsing | When skill has args |
+| `<workflow>` | High-level numbered steps | Always |
+| `<state_variables>` | Persistent variables table | Progressive skills |
+| `<entry_point>` | First step to load | Progressive skills |
+| `<step_files>` | Step file mapping table | Progressive skills |
+| `<execution_rules>` | Key constraints | Always |
+| `<security_rules>` | Mandatory security checks | When security-critical |
+| `<success_criteria>` | Completion conditions | Always |
+
+## Pattern 6: State Variables
+
+Persist data across progressive steps.
+
+```xml
+<state_variables>
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{name}` | string | Item name |
+| `{scope}` | string | Target scope |
+| `{auto_mode}` | boolean | Skip confirmations |
+| `{items}` | object[] | Collected items |
+</state_variables>
+```
+
+Variables are referenced as `{variable_name}` throughout steps and are maintained in conversation context.
+
+## Pattern 7: AskUserQuestion Integration
+
+Use AskUserQuestion for interactive choices.
+
+```yaml
+AskUserQuestion:
+  header: "Short Label"        # Max 12 chars
+  question: "Full question?"
+  options:
+    - label: "Option A (Recommended)"
+      description: "What this option does"
+    - label: "Option B"
+      description: "What this option does"
+  multiSelect: false           # true for checkboxes
+```
+
+## Pattern 8: Skill Chaining
+
+Call other skills from within a skill.
+
+```markdown
+After completing this step:
+1. Run `/other-skill arg1`
+2. Continue with next step
+```
+
+Or use the Skill tool:
+```
+Use Skill tool: skill="other-skill", args="arg1 arg2"
+```
+
+## Pattern 9: MCP Tool Integration
+
+Call MCP tools from skill steps.
+
+```markdown
+### Validate conventions
+Call `mcp__smartstack__validate_conventions` with:
+  - target: "{entity_path}"
+  - type: "controller"
+```
+
+## Pattern 10: Compact Output Tables
+
+Display results in scannable tables, not prose.
+
+```markdown
+| Property | Value |
+|----------|-------|
+| Name | {name} |
+| Status | OK |
+| Files | 3 created |
+```

package/templates/skills/cc-skill/steps/step-00-init.md

@@ -0,0 +1,119 @@
+---
+name: step-00-init
+description: Parse subcommand, skill name, scope, and resolve target directory
+next_step: steps/step-01-design.md
+---
+
+# Step 0: Initialization
+
+## MANDATORY EXECUTION RULES:
+- ALWAYS parse subcommand first (create or update)
+- ALWAYS validate skill name format
+- ALWAYS resolve target directory before proceeding
+- For UPDATE: verify skill exists before continuing
+
+## YOUR TASK:
+Parse input arguments, validate the skill name, and resolve the target directory.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Parse Input
+
+```
+Arguments from $ARGUMENTS:
+  First word  → {subcommand} ("create" or "update")
+  Second word → {skill_name} (lowercase, kebab-case)
+  --scope X   → {scope} (default: "project")
+  --type X    → {skill_type} (optional, skip type selection in step-01)
+
+Valid subcommands: create, update
+Valid scopes: project, global, templates
+Valid types: simple, progressive, forked
+```
+
+If {subcommand} is missing or invalid:
+
+```yaml
+AskUserQuestion:
+  header: "Action"
+  question: "What do you want to do?"
+  options:
+    - label: "Create"
+      description: "Create a new skill from scratch"
+    - label: "Update"
+      description: "Update an existing skill"
+```
+
+### 2. Validate Skill Name
+
+If {skill_name} missing:
+
+```yaml
+AskUserQuestion:
+  header: "Name"
+  question: "What is the skill name? (lowercase, kebab-case, max 64 chars)"
+```
+
+Validation rules:
+- Lowercase only
+- Kebab-case (hyphens, no spaces or underscores)
+- Max 64 characters
+- No special characters except hyphens
+- Must not conflict with existing built-in commands (/help, /clear, /compact, etc.)
+
+### 3. Resolve Target Directory
+
+```
+Based on {scope}:
+
+  "project" →
+    {target_dir} = "{cwd}/.claude/skills/{skill_name}/"
+
+  "global" →
+    {target_dir} = "~/.claude/skills/{skill_name}/"
+    Resolve ~ to actual home directory
+
+  "templates" →
+    {target_dir} = "{cwd}/templates/skills/{skill_name}/"
+    Verify this is a SmartStack CLI project (templates/ exists)
+```
+
+### 4. Check Existing
+
+**For CREATE:**
+- Verify {target_dir} does NOT already exist
+- If exists: warn and ask to overwrite or switch to update
+
+**For UPDATE:**
+- Verify {target_dir} exists and contains SKILL.md
+- If missing: warn and ask to switch to create
+- If exists: read SKILL.md and extract current frontmatter
+
+### 5. Show Summary
+
+```
+Skill Configuration:
+
+| Setting | Value |
+|---------|-------|
+| Action | {subcommand} |
+| Name | {skill_name} |
+| Scope | {scope} |
+| Target | {target_dir} |
+| Type | {skill_type} (if pre-set) |
+
+→ Designing skill...
+```
+
+---
+
+## SUCCESS METRICS:
+- Subcommand correctly identified
+- Skill name validated
+- Target directory resolved and checked
+- Summary displayed
+
+## NEXT STEP:
+After showing summary, proceed directly to `./step-01-design.md`