@atlashub/smartstack-cli 1.37.0 → 2.1.0

package/templates/skills/cc-skill/steps/step-01-design.md

@@ -0,0 +1,199 @@
+---
+name: step-01-design
+description: Choose skill type, gather frontmatter information via interactive questions
+next_step: steps/step-02-generate.md
+---
+
+# Step 1: Design Skill
+
+## MANDATORY EXECUTION RULES:
+- ALWAYS ask the user for design decisions (don't assume)
+- For UPDATE: show current values and ask what to change
+- Load reference docs for guidance
+- Gather ALL needed information before proceeding to generation
+
+## YOUR TASK:
+Guide the user through skill design decisions. Gather all frontmatter fields and structural choices.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Load References
+
+```
+Read: "references/frontmatter-reference.md"
+Read: "references/skill-patterns.md"
+Read: "references/best-practices.md"
+```
+
+### 2. Choose Skill Type (if not pre-set)
+
+If {skill_type} is not already set:
+
+```yaml
+AskUserQuestion:
+  header: "Type"
+  question: "What type of skill do you want to create?"
+  options:
+    - label: "Simple"
+      description: "Single SKILL.md file, no steps. Best for simple tasks or knowledge injection."
+    - label: "Progressive"
+      description: "SKILL.md + step files. Best for complex multi-phase workflows."
+    - label: "Forked"
+      description: "Runs in isolated subagent context. Best for research/exploration tasks."
+```
+
+### 3. Gather Description
+
+```yaml
+AskUserQuestion:
+  header: "Description"
+  question: "Describe what this skill does and WHEN Claude should use it. Include trigger keywords. Example: 'Generate API controllers. Use when: creating controllers, API endpoints, REST routes'"
+```
+
+Store in {description}.
+
+### 4. Gather Invocation Settings
+
+```yaml
+AskUserQuestion:
+  header: "Invocation"
+  question: "How should this skill be invoked?"
+  options:
+    - label: "Auto + Manual (Recommended)"
+      description: "Claude auto-invokes when relevant AND user can invoke with /name"
+    - label: "Manual only"
+      description: "Only user can invoke with /name. Best for side-effect operations (deploy, commit)."
+    - label: "Hidden"
+      description: "Not visible in /menu. Background knowledge only."
+```
+
+Map to:
+- Auto + Manual → {disable_model_invocation} = false, {user_invocable} = true
+- Manual only → {disable_model_invocation} = true, {user_invocable} = true
+- Hidden → {disable_model_invocation} = false, {user_invocable} = false
+
+### 5. Gather Arguments (if applicable)
+
+```yaml
+AskUserQuestion:
+  header: "Arguments"
+  question: "Does this skill accept arguments? If yes, describe the format (e.g., '<name> [--flag]'). If no, type 'none'."
+```
+
+Store in {argument_hint} (or null if "none").
+
+### 6. Gather Model Preference
+
+```yaml
+AskUserQuestion:
+  header: "Model"
+  question: "Which model should this skill use?"
+  options:
+    - label: "Inherit (Recommended)"
+      description: "Use whatever model the user has configured"
+    - label: "Haiku"
+      description: "Fast and cheap. Best for simple, repetitive tasks."
+    - label: "Sonnet"
+      description: "Balanced. Good for most tasks."
+    - label: "Opus"
+      description: "Most capable. Best for complex reasoning."
+```
+
+### 7. Gather Tools (if applicable)
+
+If {skill_type} is "forked":
+
+```yaml
+AskUserQuestion:
+  header: "Tools"
+  question: "Which tools should this skill have access to? (comma-separated)"
+  options:
+    - label: "Read-only (Recommended)"
+      description: "Read, Grep, Glob, WebSearch, WebFetch"
+    - label: "Read + Write"
+      description: "Read, Write, Edit, Grep, Glob, Bash"
+    - label: "Full access"
+      description: "All tools available"
+```
+
+Also ask for agent type:
+
+```yaml
+AskUserQuestion:
+  header: "Agent"
+  question: "Which agent type for the forked context?"
+  options:
+    - label: "Explore (Recommended)"
+      description: "Fast, read-only, optimized for searching"
+    - label: "Plan"
+      description: "Research and design, read-only"
+    - label: "general-purpose"
+      description: "Complex tasks, all tools"
+```
+
+### 8. Progressive Steps Design (if applicable)
+
+If {skill_type} is "progressive":
+
+Ask: "How many steps does this skill need? Describe each step briefly."
+
+For each step, gather:
+- Step number (00, 01, 02, ...)
+- Step name (kebab-case)
+- Step description (one line)
+
+Store in {steps}:
+```json
+[
+  {"number": "00", "name": "init", "description": "Parse arguments and initialize state"},
+  {"number": "01", "name": "analyze", "description": "Analyze the codebase"},
+  {"number": "02", "name": "generate", "description": "Generate output files"},
+  {"number": "03", "name": "validate", "description": "Validate results"}
+]
+```
+
+Also ask about state variables:
+
+Ask: "What state variables should persist across steps? (name, type, description for each)"
+
+Store in {state_vars}.
+
+### 9. Show Design Summary
+
+```
+Skill Design:
+
+| Field | Value |
+|-------|-------|
+| Name | {skill_name} |
+| Type | {skill_type} |
+| Description | {description} (truncated) |
+| Invocation | auto+manual / manual-only / hidden |
+| Arguments | {argument_hint} |
+| Model | {model} |
+| Tools | {allowed_tools} (if forked) |
+| Agent | {agent} (if forked) |
+| Steps | {step_count} (if progressive) |
+
+Step plan (if progressive):
+| # | Name | Description |
+|---|------|-------------|
+| 00 | {name} | {desc} |
+| 01 | {name} | {desc} |
+| ... | ... | ... |
+
+→ Generating skill files...
+```
+
+---
+
+## SUCCESS METRICS:
+- All required fields gathered from user
+- Skill type chosen and appropriate options collected
+- Steps defined (if progressive)
+- Design summary displayed and confirmed
+
+## NEXT STEP:
+After design is confirmed, proceed directly to `./step-02-generate.md`

package/templates/skills/cc-skill/steps/step-02-generate.md

@@ -0,0 +1,145 @@
+---
+name: step-02-generate
+description: Generate SKILL.md file from template based on design choices
+next_step: steps/step-03-steps.md
+---
+
+# Step 2: Generate SKILL.md
+
+## MANDATORY EXECUTION RULES:
+- ALWAYS load the appropriate template from `templates/` directory
+- ALWAYS use the design choices from Step 1
+- For UPDATE: read existing SKILL.md first, then apply changes
+- Generate COMPLETE SKILL.md (not a stub)
+
+## YOUR TASK:
+Generate the SKILL.md file based on the skill type and design choices gathered in Step 1.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Load Template
+
+Based on {skill_type}:
+
+```
+"simple"      → Read: "templates/skill-simple.md"
+"progressive" → Read: "templates/skill-progressive.md"
+"forked"      → Read: "templates/skill-forked.md"
+```
+
+### 2. Create Directory Structure
+
+```bash
+# Create skill directory
+mkdir -p {target_dir}
+
+# For progressive skills, create subdirectories
+mkdir -p {target_dir}/steps/
+mkdir -p {target_dir}/references/  # optional but recommended
+mkdir -p {target_dir}/templates/   # optional, for code templates
+```
+
+### 3. Generate SKILL.md
+
+Use the loaded template as a base. Replace all placeholders with actual values:
+
+**Frontmatter generation:**
+
+```yaml
+---
+name: {skill_name}
+description: |
+  {description}
+```
+
+Add optional fields only if they differ from defaults:
+
+```yaml
+# Only if manual-only
+disable-model-invocation: true
+
+# Only if hidden
+user-invocable: false
+
+# Only if skill accepts arguments
+argument-hint: "{argument_hint}"
+
+# Only if not "inherit"
+model: {model}
+
+# Only for forked skills
+context: fork
+agent: {agent}
+allowed-tools: "{allowed_tools}"
+```
+
+Close frontmatter:
+
+```yaml
+---
+```
+
+**Content generation:**
+
+Generate appropriate XML sections based on {skill_type}:
+
+**All types get:**
+- `<objective>` - One paragraph from {description}
+- `<quick_start>` - Usage examples with /skill_name
+- `<execution_rules>` - Standard rules
+- `<success_criteria>` - Completion conditions
+
+**Progressive type additionally gets:**
+- `<parameters>` with `<flags>` and `<examples>`
+- `<workflow>` - Numbered high-level steps
+- `<state_variables>` - Table of persistent variables
+- `<entry_point>` - Points to step-00-init.md
+- `<step_files>` - Table mapping steps to files
+
+**Forked type additionally gets:**
+- Note about isolated context
+- Direct workflow (no step loading)
+
+### 4. Write SKILL.md
+
+Use Write tool to create `{target_dir}/SKILL.md` with generated content.
+
+### 5. For UPDATE subcommand
+
+If {subcommand} = "update":
+1. Read existing `{target_dir}/SKILL.md`
+2. Parse current frontmatter and sections
+3. Apply only the requested changes (merge, don't replace entirely)
+4. Use Edit tool to modify specific sections
+5. Preserve any custom content not being updated
+
+### 6. Confirm Generation
+
+```
+Generated: {target_dir}/SKILL.md ({line_count} lines)
+
+Frontmatter:
+  name: {skill_name}
+  description: {description} (truncated)
+  type: {skill_type}
+  ...
+
+Sections: {list of XML sections included}
+
+→ Generating step files...
+```
+
+---
+
+## SUCCESS METRICS:
+- SKILL.md created/updated at correct path
+- Frontmatter includes all required fields
+- Appropriate XML sections for skill type
+- Under 500 lines
+- No placeholder text left unreplaced
+
+## NEXT STEP:
+- If {skill_type} = "progressive" → proceed to `./step-03-steps.md`
+- If {skill_type} = "simple" or "forked" → skip to `./step-04-validate.md`

package/templates/skills/cc-skill/steps/step-03-steps.md

@@ -0,0 +1,151 @@
+---
+name: step-03-steps
+description: Generate step files for progressive step loading skills
+next_step: steps/step-04-validate.md
+---
+
+# Step 3: Generate Step Files
+
+## MANDATORY EXECUTION RULES:
+- ONLY execute this step for progressive skills ({skill_type} = "progressive")
+- If not progressive, skip directly to step-04-validate.md
+- Generate ALL step files with proper chaining
+- Each step must follow the standard format
+
+## YOUR TASK:
+Generate step files for progressive step loading. Each step file must have proper frontmatter, sections, and next_step chaining.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Load Step Template
+
+```
+Read: "templates/step-template.md"
+```
+
+### 2. Generate Each Step File
+
+For each step in {steps} array (from Step 1 design):
+
+**File path:** `{target_dir}/steps/step-{number}-{name}.md`
+
+**Frontmatter:**
+
+```yaml
+---
+name: step-{number}-{name}
+description: {step_description}
+next_step: steps/step-{next_number}-{next_name}.md
+---
+```
+
+For the LAST step: omit `next_step` field.
+
+**Content structure for each step:**
+
+```markdown
+# Step {N}: {Title}
+
+## MANDATORY EXECUTION RULES:
+- [Rules specific to this step]
+- FORBIDDEN to skip to next step until this step is complete
+
+## YOUR TASK:
+{step_description}
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. [First subtask]
+[Instructions for the first subtask]
+
+### 2. [Second subtask]
+[Instructions for the second subtask]
+
+### N. Show Summary
+[Display step results in compact format]
+
+---
+
+## SUCCESS METRICS:
+- [What indicates this step succeeded]
+- [Measurable outcomes]
+
+## NEXT STEP:
+After showing summary, proceed directly to `./step-{next_number}-{next_name}.md`
+```
+
+### 3. Special Handling for Step 00 (Init)
+
+The first step (step-00-init) should always include:
+
+```markdown
+## EXECUTION SEQUENCE:
+
+### 1. Parse Input
+Parse flags and arguments from $ARGUMENTS.
+[Include flag parsing based on skill's <parameters>]
+
+### 2. Validate Input
+[Validate required fields, ask user if missing]
+
+### 3. Initialize State
+[Set all state variables to defaults or parsed values]
+
+### 4. Show Summary
+Display compact initialization summary table.
+```
+
+### 4. Special Handling for Last Step
+
+The last step should include:
+
+```markdown
+## EXECUTION SEQUENCE:
+
+### 1. [Final validation or action]
+
+### 2. Final Summary
+Display:
+- What was accomplished
+- Files created/modified
+- Any warnings or next steps
+
+## NEXT STEP:
+This is the final step. Skill execution is complete.
+```
+
+### 5. Write All Step Files
+
+Use Write tool for each step file. Run writes in parallel if possible.
+
+### 6. Confirm Generation
+
+```
+Generated {step_count} step files:
+
+| File | Next Step |
+|------|-----------|
+| steps/step-00-{name}.md | → step-01-{name}.md |
+| steps/step-01-{name}.md | → step-02-{name}.md |
+| ... | ... |
+| steps/step-{N}-{name}.md | (final) |
+
+→ Validating skill...
+```
+
+---
+
+## SUCCESS METRICS:
+- All step files created in {target_dir}/steps/
+- Each step has proper frontmatter (name, description, next_step)
+- Step chaining is correct (no broken references)
+- First step handles initialization
+- Last step has completion summary
+- Standard sections present in each step
+
+## NEXT STEP:
+After generating all step files, proceed directly to `./step-04-validate.md`

package/templates/skills/cc-skill/steps/step-04-validate.md

@@ -0,0 +1,124 @@
+---
+name: step-04-validate
+description: Validate generated skill structure and display final summary
+---
+
+# Step 4: Validate Skill
+
+## MANDATORY EXECUTION RULES:
+- Validate ALL generated files
+- Check frontmatter completeness
+- Verify step chaining (if progressive)
+- Display actionable report if issues found
+
+## YOUR TASK:
+Validate the generated skill against official Claude Code conventions and display a final summary.
+
+---
+
+## EXECUTION SEQUENCE:
+
+### 1. Read Generated Files
+
+```
+Read: "{target_dir}/SKILL.md"
+
+If progressive:
+  Glob: "{target_dir}/steps/step-*.md"
+  Read each step file
+```
+
+### 2. Validate SKILL.md
+
+**Frontmatter checks:**
+- [ ] `name` exists, lowercase, max 64 chars
+- [ ] `description` exists, non-empty
+- [ ] `argument-hint` present (if skill accepts args)
+- [ ] `disable-model-invocation` set for side-effect skills
+- [ ] `model` is valid (inherit/haiku/sonnet/opus) or absent
+
+**Content checks:**
+- [ ] Has `<objective>` section
+- [ ] Has `<quick_start>` with examples
+- [ ] Line count < 500
+- [ ] No unreplaced placeholders (e.g., `{placeholder}`)
+
+**Progressive-specific checks:**
+- [ ] Has `<entry_point>` pointing to first step
+- [ ] Has `<step_files>` listing all steps
+- [ ] Has `<state_variables>` documenting persistent state
+- [ ] Has `<workflow>` describing high-level flow
+
+### 3. Validate Step Files (if progressive)
+
+For each step file:
+- [ ] Has YAML frontmatter with `name` and `description`
+- [ ] Has `next_step` (except last step)
+- [ ] `next_step` path resolves to existing file
+- [ ] Has sections: YOUR TASK, EXECUTION SEQUENCE, SUCCESS METRICS
+- [ ] Last step has completion message (no next_step)
+
+**Chain validation:**
+```
+step-00 → step-01 → step-02 → ... → step-N (final)
+Verify: each next_step file exists
+Verify: no circular references
+Verify: no orphan steps (steps not in chain)
+```
+
+### 4. Validate File References
+
+Check all file paths referenced in SKILL.md and step files:
+- Templates referenced exist in `templates/`
+- References referenced exist in `references/`
+- Scripts referenced exist in `scripts/`
+
+### 5. Display Validation Report
+
+```
+Skill Validation Report:
+
+| Check | Status |
+|-------|--------|
+| Frontmatter complete | PASS/FAIL |
+| Content sections | PASS/FAIL |
+| Line count ({N} lines) | PASS/WARN |
+| Step chaining | PASS/FAIL/N/A |
+| File references | PASS/FAIL |
+
+{If any FAIL: show specific issues and recommendations}
+```
+
+### 6. Display Final Summary
+
+```
+Skill Created Successfully!
+
+| Property | Value |
+|----------|-------|
+| Name | {skill_name} |
+| Type | {skill_type} |
+| Location | {target_dir} |
+| Invocation | /cc-skill {skill_name} |
+| Files | {file_count} |
+
+Files created:
+  {target_dir}/SKILL.md
+  {target_dir}/steps/step-00-init.md (if progressive)
+  {target_dir}/steps/step-01-*.md (if progressive)
+  ...
+
+Next steps:
+- Test the skill: /{skill_name}
+- Add references: {target_dir}/references/
+- Add templates: {target_dir}/templates/
+- Run audit: /cc-audit
+```
+
+---
+
+## SUCCESS METRICS:
+- All validations pass (or issues clearly reported)
+- Final summary displayed with file list
+- Next steps provided to the user
+- Skill is ready to use

package/templates/skills/cc-skill/templates/skill-forked.md

@@ -0,0 +1,85 @@
+# Template: Forked Context Skill
+
+Use this template when creating a skill that runs in an isolated subagent context. Best for research, exploration, or tasks that need a clean context.
+
+## Generated SKILL.md format:
+
+```yaml
+---
+name: {{SKILL_NAME}}
+description: |
+  {{DESCRIPTION}}
+{{#if ARGUMENT_HINT}}
+argument-hint: "{{ARGUMENT_HINT}}"
+{{/if}}
+context: fork
+agent: {{AGENT_TYPE}}
+allowed-tools: "{{ALLOWED_TOOLS}}"
+{{#if DISABLE_MODEL_INVOCATION}}
+disable-model-invocation: true
+{{/if}}
+{{#if MODEL}}
+model: {{MODEL}}
+{{/if}}
+---
+
+<objective>
+{{OBJECTIVE}}
+
+**Note:** This skill runs in an isolated context. Use allowed tools directly - do NOT launch Task agents.
+</objective>
+
+<quick_start>
+
+` ` `bash
+/{{SKILL_NAME}} {{EXAMPLE_ARGS_1}}
+/{{SKILL_NAME}} {{EXAMPLE_ARGS_2}}
+` ` `
+
+</quick_start>
+
+## Task
+{{TASK_DESCRIPTION}}: $ARGUMENTS
+
+<workflow>
+
+## 1. Parse Input
+- Extract key information from the input
+- Identify scope and targets
+
+## 2. {{MAIN_PHASE}}
+{{MAIN_PHASE_INSTRUCTIONS}}
+
+## 3. Report Results
+- Provide comprehensive answer
+- Reference file paths and line numbers
+- Include relevant code examples
+
+</workflow>
+
+<execution_rules>
+- **PARALLEL SEARCH**: Run independent searches simultaneously
+- **CITE SOURCES**: Always reference file paths and line numbers
+- **STAY FOCUSED**: Only explore what is needed
+- **NO TASK AGENTS**: Use allowed tools directly (context is already forked)
+- {{RULE_1}}
+</execution_rules>
+
+<priority>
+{{PRIORITY_STATEMENT}}
+</priority>
+```
+
+## Agent Types:
+| Agent | Tools | Best for |
+|-------|-------|----------|
+| `Explore` | Read, Grep, Glob | Fast codebase search |
+| `Plan` | Read, Grep, Glob | Research and design |
+| `general-purpose` | All tools | Complex tasks |
+
+## Notes:
+- Forked skills run in isolated context (separate conversation)
+- Use `allowed-tools` to limit tool access
+- $ARGUMENTS passes user input to the forked context
+- Do NOT use progressive step loading with forked skills
+- Best for: code search, documentation lookup, research, analysis