flake-update-20260505

name: create-skill description: Skill creation framework for creating, validating, updating, or canonicalizing skills. USE WHEN user wants to create a new skill, validate skill structure, update existing skill, or fix skill compliance.

Create Skill

Systematic skill creation framework for building consistent, well-structured Claude Code skills.

Context Detection

This skill activates when:

  • User wants to create a new skill
  • User asks to validate, update, or fix an existing skill
  • User mentions skill structure, compliance, or canonicalization
  • User is working in /home/vincent/.config/claude/skills/ directory
  • User asks about skill creation best practices or framework

Naming Convention

All naming must use lowercase-with-hyphens (kebab-case).

Component Format Example
Skill directory lowercase-with-hyphens golang, homelab, create-skill
Workflow files TitleCase.md Create.md, UpdateInfo.md
Reference docs TitleCase.md Guide.md, Reference.md
Tool files kebab-case.sh manage-tool.sh

Wrong (NEVER use):

  • Createskill, CREATE_SKILL, CreateSkill
  • SYNC_REPO.md

Workflow Routing

When executing a workflow, output this notification directly:

Running the **WorkflowName** workflow from the **create-skill** skill...
Workflow Trigger File
CreateSkill “create a new skill” workflows/CreateSkill.md
ValidateSkill “validate skill”, “check skill” workflows/ValidateSkill.md

Skill Structure Requirements

Required Components

Every skill must have:

  1. SKILL.md - Main skill file with:

    • YAML frontmatter (name, description)
    • Clear purpose and scope
    • Workflow routing table
    • Usage examples

  2. workflows/ directory - Contains workflow markdown files

  3. tools/ directory - Contains tool scripts (optional)

YAML Frontmatter Format

---
name: create-skill
description: Single-line description. USE WHEN triggers go here.
---

Critical Rules:

  • name must be lowercase-with-hyphens, matching the directory name
  • description must be ONE LINE (no newlines)
  • Include “USE WHEN” triggers in description

Markdown Body Structure

Required sections in order:

  1. # [Skill Name] - H1 heading matching the name
  2. Brief overview - What this skill does
  3. Workflow Routing - Table of workflows
  4. Examples - Usage examples (at least one)

Examples

Example 1: Create a new skill from scratch

User: "Create a skill for managing my Docker containers"
→ Invokes CreateSkill workflow
→ Creates skill directory with kebab-case naming
→ Creates SKILL.md with proper frontmatter
→ Creates workflows/ and tools/ directories
→ Generates USE WHEN triggers based on purpose

Example 2: Validate an existing skill

User: "Validate the golang skill"
→ Invokes ValidateSkill workflow
→ Checks SKILL.md structure and naming
→ Verifies kebab-case naming for directory and name field
→ Verifies USE WHEN triggers are clear
→ Reports any compliance issues

Best Practices

Naming

  • Use lowercase-with-hyphens for skill directories and the YAML name field
  • Keep names descriptive but concise
  • The name field in frontmatter must match the directory name

Description Field

  • Keep it to ONE LINE only
  • Include clear USE WHEN triggers
  • Focus on when to invoke the skill, not just what it does

Workflows

  • Name workflows with clear action verbs (Create, Update, Validate)
  • Keep workflows focused on single tasks
  • Use TitleCase.md naming for workflow files

Tools

  • Prefer shell scripts for tools (simplicity, portability)
  • Use Python only when complexity requires it (complex parsing, data structures)
  • Avoid TypeScript - not preferred for skill tools
  • Name tools with kebab-case.sh or kebab-case.py
  • Keep tools focused and single-purpose

Dependency Management:

  • For shell scripts with dependencies: Use nix-shell shebang for maximum portability 
    #!/usr/bin/env nix-shell
#! nix-shell -i bash -p jq curl
  • For Python scripts with dependencies: Use uv shebang for isolated environments 
    #!/usr/bin/env -S uv run --quiet --script
# /// script
# dependencies = ["requests", "click"]
# ///
  • This makes scripts portable without requiring global installation of dependencies

Examples

  • Provide at least one concrete example
  • Show the trigger phrase and expected behavior
  • Demonstrate the value of the skill

Integration

This skill works with your existing skills:

  • References .config/claude/skills/ directory structure
  • Follows patterns from CORE, golang, nix, homelab, notes skills
  • Validates against established conventions