@yeongjaeyou/claude-code-config 0.16.0 → 0.17.0

package/.claude/skills/skill-creator/scripts/quick_validate.py

@@ -6,52 +6,82 @@ Quick validation script for skills - minimal version
 import sys
 import os
 import re
+import yaml
 from pathlib import Path
 
 def validate_skill(skill_path):
     """Basic validation of a skill"""
     skill_path = Path(skill_path)
-    
+
     # Check SKILL.md exists
     skill_md = skill_path / 'SKILL.md'
     if not skill_md.exists():
         return False, "SKILL.md not found"
-    
+
     # Read and validate frontmatter
     content = skill_md.read_text()
     if not content.startswith('---'):
         return False, "No YAML frontmatter found"
-    
+
     # Extract frontmatter
     match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
     if not match:
         return False, "Invalid frontmatter format"
-    
-    frontmatter = match.group(1)
-    
+
+    frontmatter_text = match.group(1)
+
+    # Parse YAML frontmatter
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+        if not isinstance(frontmatter, dict):
+            return False, "Frontmatter must be a YAML dictionary"
+    except yaml.YAMLError as e:
+        return False, f"Invalid YAML in frontmatter: {e}"
+
+    # Define allowed properties
+    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'}
+
+    # Check for unexpected properties (excluding nested keys under metadata)
+    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
+    if unexpected_keys:
+        return False, (
+            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
+            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
+        )
+
     # Check required fields
-    if 'name:' not in frontmatter:
+    if 'name' not in frontmatter:
         return False, "Missing 'name' in frontmatter"
-    if 'description:' not in frontmatter:
+    if 'description' not in frontmatter:
         return False, "Missing 'description' in frontmatter"
-    
+
     # Extract name for validation
-    name_match = re.search(r'name:\s*(.+)', frontmatter)
-    if name_match:
-        name = name_match.group(1).strip()
+    name = frontmatter.get('name', '')
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}"
+    name = name.strip()
+    if name:
         # Check naming convention (hyphen-case: lowercase with hyphens)
         if not re.match(r'^[a-z0-9-]+$', name):
             return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"
         if name.startswith('-') or name.endswith('-') or '--' in name:
             return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+        # Check name length (max 64 characters per spec)
+        if len(name) > 64:
+            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
 
     # Extract and validate description
-    desc_match = re.search(r'description:\s*(.+)', frontmatter)
-    if desc_match:
-        description = desc_match.group(1).strip()
+    description = frontmatter.get('description', '')
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}"
+    description = description.strip()
+    if description:
         # Check for angle brackets
         if '<' in description or '>' in description:
             return False, "Description cannot contain angle brackets (< or >)"
+        # Check description length (max 1024 characters per spec)
+        if len(description) > 1024:
+            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
 
     return True, "Skill is valid!"
 

package/.claude/skills/slash-command-creator/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: slash-command-creator
+description: Guide for creating Claude Code slash commands. Use when the user wants to create a new slash command, update an existing slash command, or asks about slash command syntax, frontmatter options, or best practices.
+---
+
+# Slash Command Creator
+
+Create custom slash commands for Claude Code to automate frequently-used prompts.
+
+## Quick Start
+
+Initialize a new command:
+```bash
+scripts/init_command.py <command-name> [--scope project|personal]
+```
+
+## Command Structure
+
+Slash commands are Markdown files with optional YAML frontmatter:
+
+```markdown
+---
+description: Brief description shown in /help
+---
+
+Your prompt instructions here.
+
+$ARGUMENTS
+```
+
+### File Locations
+
+| Scope    | Path                    | Shown as           |
+|----------|-------------------------|-------------------|
+| Project  | `.claude/commands/`     | (project)         |
+| Personal | `~/.claude/commands/`   | (user)            |
+
+### Namespacing
+
+Organize commands in subdirectories:
+- `.claude/commands/frontend/component.md` → `/component` shows "(project:frontend)"
+- `~/.claude/commands/backend/api.md` → `/api` shows "(user:backend)"
+
+## Features
+
+### Arguments
+
+**All arguments** - `$ARGUMENTS`:
+```markdown
+Fix issue #$ARGUMENTS following our coding standards
+# /fix-issue 123 → "Fix issue #123 following..."
+```
+
+**Positional** - `$1`, `$2`, etc.:
+```markdown
+Review PR #$1 with priority $2
+# /review 456 high → "Review PR #456 with priority high"
+```
+
+### Bash Execution
+
+Execute shell commands with `!` prefix (requires `allowed-tools` in frontmatter):
+
+```markdown
+---
+allowed-tools: Bash(git status:*), Bash(git diff:*)
+---
+
+Current status: !`git status`
+Changes: !`git diff HEAD`
+```
+
+### File References
+
+Include file contents with `@` prefix:
+
+```markdown
+Review @src/utils/helpers.js for issues.
+Compare @$1 with @$2.
+```
+
+## Frontmatter Options
+
+| Field                     | Purpose                                | Required |
+|---------------------------|----------------------------------------|----------|
+| `description`             | Brief description for /help            | Yes      |
+| `allowed-tools`           | Tools the command can use              | No       |
+| `argument-hint`           | Expected arguments hint                | No       |
+| `model`                   | Specific model to use                  | No       |
+| `disable-model-invocation`| Prevent SlashCommand tool invocation   | No       |
+
+See [references/frontmatter.md](references/frontmatter.md) for detailed reference.
+
+## Examples
+
+See [references/examples.md](references/examples.md) for complete examples including:
+- Simple review/explain commands
+- Commands with positional arguments
+- Git workflow commands with bash execution
+- Namespaced commands for frontend/backend
+
+## Creation Workflow
+
+1. **Identify the use case**: What prompt do you repeat often?
+2. **Choose scope**: Project (shared) or personal (private)?
+3. **Initialize**: Run `scripts/init_command.py <name>`
+4. **Edit**: Update description and body
+5. **Test**: Run the command in Claude Code

package/.claude/skills/slash-command-creator/references/examples.md

@@ -0,0 +1,161 @@
+# Slash Command Examples
+
+## Simple Commands
+
+### Code Review Command
+```markdown
+---
+description: Review code for bugs and improvements
+---
+
+Review this code for:
+- Security vulnerabilities
+- Performance issues
+- Code style violations
+- Potential bugs
+
+$ARGUMENTS
+```
+
+### Explain Command
+```markdown
+---
+description: Explain code in simple terms
+---
+
+Explain the following code in simple, easy-to-understand terms:
+
+$ARGUMENTS
+```
+
+## Commands with Arguments
+
+### Single Argument (`$ARGUMENTS`)
+```markdown
+---
+description: Fix a GitHub issue
+---
+
+Fix issue #$ARGUMENTS following our coding standards.
+```
+
+### Positional Arguments (`$1`, `$2`, etc.)
+```markdown
+---
+argument-hint: [pr-number] [priority] [assignee]
+description: Review pull request
+---
+
+Review PR #$1 with priority $2 and assign to $3.
+Focus on security, performance, and code style.
+```
+
+## Commands with Bash Execution
+
+Use `!` prefix to execute bash commands and include output in context.
+
+### Git Commit Command
+```markdown
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+description: Create a git commit
+---
+
+## Context
+
+- Current git status: !`git status`
+- Current git diff: !`git diff HEAD`
+- Current branch: !`git branch --show-current`
+- Recent commits: !`git log --oneline -10`
+
+## Task
+
+Based on the above changes, create a single git commit.
+```
+
+### Deploy Command
+```markdown
+---
+allowed-tools: Bash(npm:*), Bash(docker:*)
+argument-hint: [environment]
+description: Deploy to specified environment
+---
+
+## Current State
+
+- Branch: !`git branch --show-current`
+- Last commit: !`git log -1 --oneline`
+
+## Deploy to $1
+
+Run the deployment process for the $1 environment.
+```
+
+## Commands with File References
+
+Use `@` prefix to include file contents.
+
+### Review Implementation
+```markdown
+---
+description: Review implementation against spec
+---
+
+Review the implementation in @src/utils/helpers.js against the specification.
+```
+
+### Compare Files
+```markdown
+---
+argument-hint: [old-file] [new-file]
+description: Compare two files
+---
+
+Compare @$1 with @$2 and summarize the differences.
+```
+
+## Namespaced Commands
+
+Commands in subdirectories appear with namespace in description.
+
+### Frontend Component (`.claude/commands/frontend/component.md`)
+```markdown
+---
+description: Generate a React component
+---
+
+Generate a React component with the following requirements:
+
+$ARGUMENTS
+
+Follow our frontend coding standards and use TypeScript.
+```
+
+### Backend API (`.claude/commands/backend/api.md`)
+```markdown
+---
+description: Generate API endpoint
+---
+
+Generate a REST API endpoint for:
+
+$ARGUMENTS
+
+Include validation, error handling, and documentation.
+```
+
+## Extended Thinking Commands
+
+Include thinking keywords to trigger extended thinking.
+
+```markdown
+---
+description: Analyze architecture deeply
+---
+
+Think step by step about the architecture implications of:
+
+$ARGUMENTS
+
+Consider scalability, maintainability, and performance.
+```

package/.claude/skills/slash-command-creator/references/frontmatter.md

@@ -0,0 +1,74 @@
+# Slash Command Frontmatter Reference
+
+## Required Fields
+
+### `description`
+Brief description of what the command does. Shown in `/help` output.
+
+```yaml
+description: Create a git commit with staged changes
+```
+
+## Optional Fields
+
+### `allowed-tools`
+Specifies which tools the command can use. Format: `ToolName(pattern:*)` or just `ToolName`.
+
+```yaml
+# Single tool
+allowed-tools: Bash(git status:*)
+
+# Multiple tools
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+
+# Tool without pattern
+allowed-tools: Read, Write, Edit
+```
+
+Common tool patterns:
+- `Bash(command:*)` - Allow specific bash commands
+- `Read` - File reading
+- `Write` - File writing
+- `Edit` - File editing
+- `Grep` - Content search
+- `Glob` - File pattern matching
+
+### `argument-hint`
+Shows expected arguments when auto-completing the command.
+
+```yaml
+# Single argument
+argument-hint: [message]
+
+# Multiple arguments
+argument-hint: [pr-number] [priority] [assignee]
+
+# Alternative syntax
+argument-hint: add [tagId] | remove [tagId] | list
+```
+
+### `model`
+Specific model to use for this command. See [Models overview](https://docs.claude.com/en/docs/about-claude/models/overview).
+
+```yaml
+model: claude-3-5-haiku-20241022
+model: claude-sonnet-4-5-20250929
+```
+
+### `disable-model-invocation`
+Prevents the `SlashCommand` tool from calling this command programmatically.
+
+```yaml
+disable-model-invocation: true
+```
+
+## Complete Frontmatter Example
+
+```yaml
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+argument-hint: [message]
+description: Create a git commit with staged changes
+model: claude-3-5-haiku-20241022
+---
+```

package/.claude/skills/slash-command-creator/scripts/init_command.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""
+Slash Command Initializer - Creates a new slash command from template
+
+Usage:
+    init_command.py <command-name> [--scope project|personal] [--path <custom-path>]
+
+Examples:
+    init_command.py review                    # Creates .claude/commands/review.md
+    init_command.py deploy --scope personal   # Creates ~/.claude/commands/deploy.md
+    init_command.py test --path ./my-commands # Creates ./my-commands/test.md
+"""
+
+import sys
+import os
+from pathlib import Path
+import argparse
+
+
+COMMAND_TEMPLATE = '''---
+description: {description}
+---
+
+# {command_title}
+
+{body}
+'''
+
+COMMAND_TEMPLATE_WITH_TOOLS = '''---
+allowed-tools: {allowed_tools}
+description: {description}
+---
+
+# {command_title}
+
+{body}
+'''
+
+COMMAND_TEMPLATE_FULL = '''---
+allowed-tools: {allowed_tools}
+argument-hint: {argument_hint}
+description: {description}
+model: {model}
+---
+
+# {command_title}
+
+{body}
+'''
+
+
+def title_case(name: str) -> str:
+    """Convert hyphenated name to Title Case."""
+    return ' '.join(word.capitalize() for word in name.replace('-', ' ').split())
+
+
+def get_project_commands_path() -> Path:
+    """Get the project-level commands directory."""
+    return Path.cwd() / '.claude' / 'commands'
+
+
+def get_personal_commands_path() -> Path:
+    """Get the user-level commands directory."""
+    return Path.home() / '.claude' / 'commands'
+
+
+def init_command(
+    command_name: str,
+    scope: str = 'project',
+    custom_path: str = None,
+    description: str = None,
+    body: str = None,
+    allowed_tools: str = None,
+    argument_hint: str = None,
+    model: str = None,
+    namespace: str = None
+) -> Path:
+    """
+    Initialize a new slash command.
+
+    Args:
+        command_name: Name of the command (without .md extension)
+        scope: 'project' or 'personal'
+        custom_path: Optional custom path override
+        description: Command description
+        body: Command body content
+        allowed_tools: Comma-separated list of allowed tools
+        argument_hint: Hint for command arguments
+        model: Specific model to use
+        namespace: Optional subdirectory namespace
+
+    Returns:
+        Path to created command file, or None if error
+    """
+    # Determine base path
+    if custom_path:
+        base_path = Path(custom_path).resolve()
+    elif scope == 'personal':
+        base_path = get_personal_commands_path()
+    else:
+        base_path = get_project_commands_path()
+
+    # Add namespace subdirectory if specified
+    if namespace:
+        base_path = base_path / namespace
+
+    # Create directory if it doesn't exist
+    try:
+        base_path.mkdir(parents=True, exist_ok=True)
+    except Exception as e:
+        print(f"Error creating directory {base_path}: {e}")
+        return None
+
+    # Create command file path
+    command_file = base_path / f'{command_name}.md'
+
+    # Check if file already exists
+    if command_file.exists():
+        print(f"Error: Command already exists: {command_file}")
+        return None
+
+    # Prepare content
+    command_title = title_case(command_name)
+    description = description or f"[TODO: Brief description of /{command_name}]"
+    body = body or f"[TODO: Add instructions for /{command_name}]\n\n$ARGUMENTS"
+
+    # Choose template based on options
+    if allowed_tools and argument_hint and model:
+        content = COMMAND_TEMPLATE_FULL.format(
+            allowed_tools=allowed_tools,
+            argument_hint=argument_hint,
+            description=description,
+            model=model,
+            command_title=command_title,
+            body=body
+        )
+    elif allowed_tools:
+        content = COMMAND_TEMPLATE_WITH_TOOLS.format(
+            allowed_tools=allowed_tools,
+            description=description,
+            command_title=command_title,
+            body=body
+        )
+    else:
+        content = COMMAND_TEMPLATE.format(
+            description=description,
+            command_title=command_title,
+            body=body
+        )
+
+    # Write command file
+    try:
+        command_file.write_text(content)
+        print(f"Created: {command_file}")
+        return command_file
+    except Exception as e:
+        print(f"Error writing command file: {e}")
+        return None
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Initialize a new Claude Code slash command',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+Examples:
+  %(prog)s review
+      Creates .claude/commands/review.md (project command)
+
+  %(prog)s deploy --scope personal
+      Creates ~/.claude/commands/deploy.md (personal command)
+
+  %(prog)s component --namespace frontend
+      Creates .claude/commands/frontend/component.md
+
+  %(prog)s commit --allowed-tools "Bash(git add:*), Bash(git commit:*)"
+      Creates command with specific tool permissions
+
+Command naming:
+  - Use lowercase with hyphens (e.g., 'review-pr', 'run-tests')
+  - Avoid spaces and special characters
+  - Keep names concise and descriptive
+'''
+    )
+
+    parser.add_argument('command_name', help='Name of the slash command (without .md)')
+    parser.add_argument('--scope', choices=['project', 'personal'], default='project',
+                        help='Command scope: project (.claude/commands) or personal (~/.claude/commands)')
+    parser.add_argument('--path', dest='custom_path', help='Custom path for command file')
+    parser.add_argument('--namespace', help='Subdirectory namespace (e.g., frontend, backend)')
+    parser.add_argument('--description', help='Command description')
+    parser.add_argument('--allowed-tools', dest='allowed_tools', help='Comma-separated list of allowed tools')
+    parser.add_argument('--argument-hint', dest='argument_hint', help='Hint for command arguments')
+    parser.add_argument('--model', help='Specific model to use (e.g., claude-3-5-haiku-20241022)')
+
+    args = parser.parse_args()
+
+    result = init_command(
+        command_name=args.command_name,
+        scope=args.scope,
+        custom_path=args.custom_path,
+        description=args.description,
+        allowed_tools=args.allowed_tools,
+        argument_hint=args.argument_hint,
+        model=args.model,
+        namespace=args.namespace
+    )
+
+    if result:
+        print(f"\nSlash command '/{args.command_name}' initialized successfully!")
+        print("\nNext steps:")
+        print("1. Edit the command file to update the description and body")
+        print("2. Test the command by running it in Claude Code")
+        print(f"\nUsage: /{args.command_name} [arguments]")
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()