@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/cc-audit/steps/step-02-analyze.md

@@ -1,158 +0,0 @@
----
-name: step-02-analyze
-description: Validate component structure, frontmatter, and cross-references
-next_step: steps/step-03-report.md
----
-
-# Step 2: Analyze Components
-
-## MANDATORY EXECUTION RULES:
-- Validate EVERY component found in Step 1
-- Load reference checklists from `references/` directory
-- Record all issues with severity (ERROR, WARN, INFO)
-- Check cross-references between component types
-
-## YOUR TASK:
-Validate each component against official Claude Code conventions and check cross-references.
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Load Checklists
-
-```
-Read reference checklists:
-  Read: "references/skill-checklist.md"
-  Read: "references/agent-checklist.md"
-  Read: "references/hook-checklist.md"
-```
-
-### 2. Validate Skills
-
-For each skill in {skills_found}, check:
-
-**Frontmatter (required):**
-- `name` exists and is lowercase, max 64 chars → ERROR if missing
-- `description` exists and is non-empty → ERROR if missing
-
-**Frontmatter (recommended):**
-- `argument-hint` present if skill accepts arguments → WARN if missing
-- `disable-model-invocation` explicitly set for side-effect skills → WARN
-
-**SKILL.md quality:**
-- Line count < 500 → WARN if exceeded
-- Contains `<objective>` section → WARN if missing
-- Contains `<entry_point>` section (if has steps/) → ERROR if missing
-- Contains `<workflow>` or `<step_files>` section → INFO if missing
-
-**Step files validation (if steps/ exists):**
-- Each step file has frontmatter with `name` and `description` → ERROR if missing
-- Each step file (except last) has `next_step` in frontmatter → ERROR if missing
-- `next_step` paths resolve to existing files → ERROR if broken
-- Steps follow sequential naming (step-00, step-01, ...) → WARN if not
-- Each step has "NEXT STEP" or "SUCCESS METRICS" section → INFO if missing
-
-**File references:**
-- All files referenced in SKILL.md exist → ERROR if missing
-- Templates, references, scripts directories referenced exist → WARN if missing
-
-**Record issues in {issues}:**
-```
-{component_name, component_type: "skill", severity, message, file_path, line_number}
-```
-
-### 3. Validate Agents
-
-For each agent in {agents_found}, check:
-
-**Frontmatter (required):**
-- `name` exists → ERROR if missing
-- `description` exists and is non-empty → ERROR if missing
-
-**Frontmatter (recommended):**
-- `model` is valid (haiku, sonnet, opus, inherit) or absent → ERROR if invalid
-- `tools` references valid tool names → WARN if unrecognized tool
-- `permissionMode` is valid (default, acceptEdits, dontAsk, bypassPermissions, plan) → ERROR if invalid
-- `skills` references existing skill names → WARN if not found
-
-**Content quality:**
-- Has workflow or instructions section → INFO if very short (< 10 lines)
-- System prompt is clear and actionable → INFO
-
-**Record issues in {issues}:**
-```
-{component_name, component_type: "agent", severity, message, file_path}
-```
-
-### 4. Validate Hooks
-
-For each hook in {hooks_found}, check:
-
-**Structure:**
-- Event name is valid (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, Stop, PreCompact, SessionEnd) → ERROR if invalid
-- Hook type is valid (command, prompt, agent) → ERROR if invalid
-
-**Command hooks:**
-- Referenced script/command exists → ERROR if missing
-- Script is executable (on Unix) → WARN if not
-
-**Prompt hooks:**
-- `prompt` field is non-empty → ERROR if missing
-- `model` is valid if specified → WARN if invalid
-
-**Matcher patterns:**
-- Regex is valid → ERROR if invalid syntax
-- Pattern matches at least one known tool/event → INFO if no match
-
-### 5. Validate Cross-References
-
-```
-Check skills → agents:
-  For skills with `context: fork` and `agent: {name}`:
-    Verify agent exists in {agents_found} or is built-in (Explore, Plan, general-purpose, Bash)
-    → WARN if agent not found
-
-Check agents → skills:
-  For agents with `skills: [...]`:
-    Verify each skill exists in {skills_found}
-    → WARN if skill not found
-
-Check hooks → scripts:
-  For command hooks:
-    Verify referenced script exists on filesystem
-    → ERROR if missing
-
-Check settings → permissions:
-  For permission rules referencing tools:
-    Verify tool names are valid
-    → WARN if unrecognized
-```
-
-### 6. Display Analysis Summary
-
-```
-Analysis Complete:
-
-| Severity | Count |
-|----------|-------|
-| ERROR | {count} |
-| WARN | {count} |
-| INFO | {count} |
-
-Top issues:
-{list top 5 most critical issues}
-
-→ Generating report...
-```
-
----
-
-## SUCCESS METRICS:
-- All components validated against checklists
-- Cross-references checked
-- All issues recorded with severity
-- Summary counts displayed
-
-## NEXT STEP:
-After showing analysis summary, proceed directly to `./step-03-report.md`

package/templates/skills/cc-audit/steps/step-03-report.md

@@ -1,142 +0,0 @@
----
-name: step-03-report
-description: Generate comprehensive audit report with recommendations
----
-
-# Step 3: Audit Report
-
-## MANDATORY EXECUTION RULES:
-- Display COMPLETE report (every component, every issue)
-- Group by component type, then by severity
-- Include actionable recommendations for each issue
-- If --fix mode, apply auto-fixes where safe
-
-## YOUR TASK:
-Generate and display the final audit report. Apply auto-fixes if requested.
-
----
-
-## EXECUTION SEQUENCE:
-
-### 1. Component Inventory Table
-
-Display full inventory:
-
-```markdown
-## Component Inventory
-
-### Skills ({count})
-| Name | Steps | Templates | Refs | Lines | Status |
-|------|-------|-----------|------|-------|--------|
-| {name} | {step_count} | {template_count} | {ref_count} | {line_count} | OK/WARN/ERROR |
-
-### Agents ({count})
-| Name | Category | Model | Tools | Status |
-|------|----------|-------|-------|--------|
-| {name} | {category} | {model} | {tool_count} | OK/WARN/ERROR |
-
-### Hooks ({count})
-| Event | Matcher | Type | Status |
-|-------|---------|------|--------|
-| {event} | {matcher} | {type} | OK/WARN/ERROR |
-```
-
-### 2. Issues Report
-
-Group by severity, then by component:
-
-```markdown
-## Issues Found
-
-### ERRORS ({count}) - Must Fix
-| Component | Type | Issue | File | Recommendation |
-|-----------|------|-------|------|----------------|
-| {name} | {type} | {message} | {file} | {recommendation} |
-
-### WARNINGS ({count}) - Should Fix
-| Component | Type | Issue | File | Recommendation |
-|-----------|------|-------|------|----------------|
-| {name} | {type} | {message} | {file} | {recommendation} |
-
-### INFO ({count}) - Nice to Have
-| Component | Type | Issue | File | Recommendation |
-|-----------|------|-------|------|----------------|
-| {name} | {type} | {message} | {file} | {recommendation} |
-```
-
-### 3. Recommendations by Issue Type
-
-Provide common fix patterns:
-
-```markdown
-## Common Fix Patterns
-
-### Missing frontmatter fields
-Add required fields to YAML frontmatter:
-- `name`: lowercase identifier, max 64 chars
-- `description`: multi-line, describe when to use
-
-### Broken step chain
-Verify `next_step` in each step file points to existing file.
-Steps should follow: step-00-init → step-01-xxx → step-02-xxx → ...
-
-### Missing agent reference
-Skills with `context: fork` need a valid `agent` field.
-Built-in agents: Explore, Plan, general-purpose, Bash
-
-### Oversized SKILL.md
-Keep SKILL.md under 500 lines. Move detailed content to:
-- references/ for documentation
-- templates/ for code templates
-- steps/ for progressive step loading
-```
-
-### 4. Auto-Fix (if --fix mode)
-
-If {fix_mode} is true, apply safe fixes:
-
-```
-Safe auto-fixes:
-  ✅ Add missing `name` field (derive from directory name)
-  ✅ Fix broken next_step paths (if obvious rename)
-  ✅ Add missing description placeholder
-  ✅ Fix invalid model values (suggest closest match)
-
-Unsafe (skip, only recommend):
-  ❌ Restructure SKILL.md sections
-  ❌ Change skill type or architecture
-  ❌ Modify hook configurations
-  ❌ Delete files
-```
-
-For each auto-fix applied:
-- Use Edit tool to modify the file
-- Record the change
-- Display what was changed
-
-### 5. Final Summary
-
-```markdown
-## Audit Summary
-
-| Metric | Value |
-|--------|-------|
-| Scope | {scope} |
-| Components scanned | {total_count} |
-| Healthy | {ok_count} |
-| With warnings | {warn_count} |
-| With errors | {error_count} |
-| Auto-fixes applied | {fix_count} (if --fix) |
-
-### Health Score: {score}%
-(100% = no errors or warnings)
-```
-
----
-
-## SUCCESS METRICS:
-- Complete report displayed with all components
-- Every issue has an actionable recommendation
-- Auto-fixes applied if --fix mode (safe fixes only)
-- Health score calculated and displayed
-- Report is scannable (tables, not prose)

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

@@ -1,134 +0,0 @@
----
-name: cc-skill
-description: |
-  Create or update Claude Code skills based on official documentation.
-  Use this skill when:
-  - Creating a new skill from scratch
-  - Updating an existing skill's structure or content
-  - Converting a simple skill to progressive step loading
-argument-hint: "<create|update> [name] [--scope project|global|templates]"
-disable-model-invocation: true
----
-
-<objective>
-Create or update Claude Code skills following official conventions. Guides the user through skill design, generates properly structured files, and validates the result.
-</objective>
-
-<quick_start>
-
-```bash
-# Create a new skill
-/cc-skill create my-skill
-/cc-skill create my-skill --scope project
-/cc-skill create my-skill --scope global
-/cc-skill create my-skill --scope templates
-
-# Update an existing skill
-/cc-skill update my-skill
-/cc-skill update my-skill --scope global
-```
-
-</quick_start>
-
-<parameters>
-
-<subcommands>
-| Command | Description | Workflow |
-|---------|-------------|----------|
-| `create` | Create a new skill from scratch | init → design → generate → steps → validate |
-| `update` | Update an existing skill | init → analyze → apply → validate |
-</subcommands>
-
-<flags>
-| Flag | Description |
-|------|-------------|
-| `--scope project` | Target `.claude/skills/` (default) |
-| `--scope global` | Target `~/.claude/skills/` |
-| `--scope templates` | Target `templates/skills/` (SmartStack CLI) |
-| `--type simple` | Skip interactive type selection |
-| `--type progressive` | Skip interactive type selection |
-| `--type forked` | Skip interactive type selection |
-</flags>
-
-<examples>
-```bash
-# Create a simple skill in current project
-/cc-skill create lint-check --type simple
-
-# Create a progressive skill for SmartStack templates
-/cc-skill create my-workflow --scope templates --type progressive
-
-# Update an existing skill
-/cc-skill update gitflow
-
-# Create a forked research skill
-/cc-skill create code-search --type forked
-```
-</examples>
-
-</parameters>
-
-<workflow>
-**Create flow:**
-1. Parse subcommand, name, scope, flags
-2. Design skill (type, frontmatter, structure)
-3. Generate SKILL.md with proper sections
-4. Generate step files (if progressive)
-5. Validate structure and conventions
-
-**Update flow:**
-1. Parse subcommand, name, scope
-2. Read and analyze existing skill
-3. Apply requested changes
-4. Validate structure and conventions
-</workflow>
-
-<state_variables>
-| Variable | Type | Description |
-|----------|------|-------------|
-| `{subcommand}` | string | create or update |
-| `{skill_name}` | string | Skill name (lowercase, max 64 chars) |
-| `{scope}` | string | project, global, or templates |
-| `{target_dir}` | string | Resolved target directory |
-| `{skill_type}` | string | simple, progressive, or forked |
-| `{description}` | string | Skill description |
-| `{user_invocable}` | boolean | Visible in /menu |
-| `{disable_model_invocation}` | boolean | Manual only |
-| `{allowed_tools}` | string | Tools without permission |
-| `{model}` | string | Model override |
-| `{argument_hint}` | string | Autocomplete hint |
-| `{step_count}` | number | Number of steps (if progressive) |
-| `{steps}` | object[] | Step definitions (name, description) |
-</state_variables>
-
-<entry_point>
-
-**FIRST ACTION:** Load `steps/step-00-init.md`
-
-</entry_point>
-
-<step_files>
-| Step | File | Purpose |
-|------|------|---------|
-| 00 | `steps/step-00-init.md` | Parse subcommand, name, scope, resolve target directory |
-| 01 | `steps/step-01-design.md` | Choose skill type, gather frontmatter info via questions |
-| 02 | `steps/step-02-generate.md` | Generate SKILL.md from template |
-| 03 | `steps/step-03-steps.md` | Generate step files (progressive only) |
-| 04 | `steps/step-04-validate.md` | Validate structure, display summary |
-</step_files>
-
-<execution_rules>
-- **Load one step at a time** - Progressive loading
-- **Ask before generating** - Confirm design choices with user
-- **Use templates** - Load from `templates/` directory for generation
-- **Follow official conventions** - Based on Claude Code documentation
-- **Validate at the end** - Check all generated files
-</execution_rules>
-
-<success_criteria>
-- Skill directory created with correct structure
-- SKILL.md has valid frontmatter and sections
-- Step files properly chained (if progressive)
-- All file references valid
-- Skill follows official Claude Code conventions
-</success_criteria>

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

@@ -1,167 +0,0 @@
-# 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