@atlashub/smartstack-cli 3.39.0 → 3.40.0

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

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