vstack 0.0.0__py3-none-any.whl

vstack/frontmatter/schema.py

@@ -0,0 +1,142 @@
+"""Frontmatter schema types — FieldSpec, FrontmatterSchema, FieldType.
+
+These are the building blocks used to declare which fields are valid in a
+frontmatter block, how to serialise them, and how to validate them.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Literal
+
+FieldType = Literal["str", "bool", "list", "object-list", "raw"]
+
+
+@dataclass
+class FieldSpec:
+    """Describes a single frontmatter field and how to serialise it.
+
+    Attributes:
+        name:                Field key as it appears in the frontmatter block.
+        type:                Serialisation type: ``"str"``, ``"bool"``, ``"list"``,
+                             ``"object-list"``, or ``"raw"`` (verbatim indented YAML block).
+        required:            When ``True``, :meth:`FrontmatterSchema.validate_meta` will
+                             flag its absence as an error.
+        max_length:          Truncate string values to this many characters before quoting.
+        quoted:              Wrap string values in single quotes (``'…'``).
+        normalize_whitespace: Collapse runs of whitespace before serialising.
+        pattern:             Optional regular expression that string values must match.
+        item_schema:         For ``"object-list"`` fields: an optional
+                             :class:`FrontmatterSchema` that describes the keys of each
+                             list item.  When set, serialisation output is ordered and
+                             filtered by this schema, and :meth:`FrontmatterSchema.validate_meta`
+                             recurses into each item.
+    """
+
+    name: str
+    type: FieldType = "str"
+    required: bool = False
+    max_length: int | None = None
+    quoted: bool = True
+    normalize_whitespace: bool = False
+    pattern: str | None = None
+    item_schema: FrontmatterSchema | None = None
+
+
+@dataclass
+class FrontmatterSchema:
+    """Ordered list of fields recognised in a frontmatter block.
+
+    Fields present in *meta* but absent from the schema are silently dropped
+    when building output.  The declaration order determines the output order.
+    """
+
+    fields: list[FieldSpec] = field(default_factory=list)
+
+    def get(self, name: str) -> FieldSpec | None:
+        """Return the :class:`FieldSpec` for *name*, or ``None`` if not declared."""
+        return next((f for f in self.fields if f.name == name), None)
+
+    @staticmethod
+    def _validate_bool_field(spec: FieldSpec, value: object, errors: list[str]) -> None:
+        """Validate one bool-like field value."""
+        if str(value).lower() not in ("true", "false"):
+            errors.append(f"field '{spec.name}' must be 'true' or 'false', got: {value!r}")
+
+    @staticmethod
+    def _validate_list_field(spec: FieldSpec, value: object, errors: list[str]) -> None:
+        """Validate one list field value."""
+        if not isinstance(value, list):
+            errors.append(f"field '{spec.name}' must be a list, got: {value!r}")
+
+    @staticmethod
+    def _validate_object_list_field(spec: FieldSpec, value: object, errors: list[str]) -> None:
+        """Validate one object-list field value."""
+        if not isinstance(value, list):
+            errors.append(f"field '{spec.name}' must be a list, got: {value!r}")
+            return
+
+        for i, item in enumerate(value):
+            if not isinstance(item, dict):
+                errors.append(f"field '{spec.name}[{i}]' must be a mapping, got: {item!r}")
+                continue
+            if spec.item_schema is None:
+                continue
+            for err in spec.item_schema.validate_meta(item):
+                errors.append(f"{spec.name}[{i}].{err}")
+
+    @staticmethod
+    def _validate_str_field(spec: FieldSpec, value: object, errors: list[str]) -> None:
+        """Validate one string-like field value."""
+        if spec.max_length and isinstance(value, str) and len(value) > spec.max_length:
+            errors.append(
+                f"field '{spec.name}' exceeds max length {spec.max_length} ({len(value)} chars)"
+            )
+        if spec.pattern and isinstance(value, str) and not re.fullmatch(spec.pattern, value):
+            errors.append(
+                f"field '{spec.name}' does not match required pattern {spec.pattern!r}: {value!r}"
+            )
+
+    def _validate_field_value(self, spec: FieldSpec, value: object, errors: list[str]) -> None:
+        """Validate a field value according to its declared field type."""
+        if spec.type == "bool":
+            self._validate_bool_field(spec, value, errors)
+            return
+        if spec.type == "list":
+            self._validate_list_field(spec, value, errors)
+            return
+        if spec.type == "object-list":
+            self._validate_object_list_field(spec, value, errors)
+            return
+        if spec.type == "raw":
+            return
+        self._validate_str_field(spec, value, errors)
+
+    def validate_meta(self, meta: dict) -> list[str]:
+        """Validate *meta* against declared schema fields.
+
+        Checks performed:
+
+        * Required fields are present and non-empty.
+        * ``"bool"`` fields contain ``"true"`` or ``"false"`` (case-insensitive).
+        * ``"list"`` fields contain a Python list.
+        * ``"object-list"`` fields contain a list of dicts; when
+          :attr:`FieldSpec.item_schema` is set each item is validated recursively.
+        * ``"str"`` fields do not exceed :attr:`FieldSpec.max_length`.
+
+        Unknown fields in *meta* (not declared in the schema) are silently ignored.
+
+        Returns:
+            A list of human-readable error strings.  An empty list means valid.
+        """
+        errors: list[str] = []
+        for spec in self.fields:
+            value = meta.get(spec.name)
+            if spec.required and not value:
+                errors.append(f"required field '{spec.name}' is missing or empty")
+                continue
+            if value is None:
+                continue
+            self._validate_field_value(spec, value, errors)
+        return errors

vstack/frontmatter/serializer.py

@@ -0,0 +1,208 @@
+"""Frontmatter serializer — schema-filtered YAML output.
+
+:class:`FrontmatterSerializer` converts a metadata dict to a ``---`` / ``---`` YAML
+frontmatter block, filtered and ordered by a :class:`~vstack.frontmatter.FrontmatterSchema`.
+Fields absent from the schema are silently dropped so generator-internal
+metadata (``version``, etc.) never leaks into output files.
+
+Main entry point: :meth:`FrontmatterSerializer.serialize`.
+"""
+
+from __future__ import annotations
+
+import re
+import textwrap
+
+from vstack.frontmatter.schema import FieldSpec, FrontmatterSchema
+
+
+class FrontmatterSerializer:
+    """Frontmatter serializer — converts metadata dict to YAML.
+
+    Instantiate once, then call :meth:`serialize` to render frontmatter.
+    No mutable instance state is retained between calls.
+    """
+
+    def _serialize_scalar(self, spec: FieldSpec, value: object) -> str:
+        """Serialize a single ``"str"`` value according to *spec* options."""
+        text = str(value)
+        if spec.normalize_whitespace:
+            text = re.sub(r"\s+", " ", text).strip()
+        if spec.max_length:
+            text = text[: spec.max_length]
+        if spec.quoted:
+            return f"'{text.replace(chr(39), chr(39) * 2)}'"
+        return text
+
+    def _serialize_multiline_scalar(
+        self, name: str, value: object, base_indent: str = ""
+    ) -> list[str]:
+        """Serialize a string scalar as YAML folded block (``>-``) lines."""
+        text = str(value).strip()
+        wrapped_lines: list[str] = []
+        for paragraph in text.splitlines() or [text]:
+            if not paragraph.strip():
+                wrapped_lines.append("")
+                continue
+            wrapped_lines.extend(textwrap.wrap(paragraph.strip(), width=100))
+        out = [f"{base_indent}{name}: >-"]
+        out.extend(f"{base_indent}  {line}" for line in wrapped_lines if line != "")
+        return out
+
+    def _should_emit_multiline(self, value: object, preserve_multiline: bool) -> bool:
+        """Return ``True`` when a scalar should use folded-block YAML output."""
+        if not preserve_multiline:
+            return False
+        text = str(value)
+        return "\n" in text or len(text) > 90
+
+    def _serialize_bool(self, value: object) -> str:
+        """Return ``"true"`` or ``"false"`` regardless of input representation."""
+        if isinstance(value, bool):
+            return str(value).lower()
+        return "true" if str(value).strip().lower() == "true" else "false"
+
+    def _serialize_object_unschematized(
+        self, item: dict, preserve_multiline: bool = False
+    ) -> list[str]:
+        """Serialize object without schema — accepts any keys/values."""
+        lines: list[str] = []
+        for k, v in item.items():
+            v_str = str(v).strip()
+            if isinstance(v, bool) or v_str.lower() in ("true", "false"):
+                lines.append(f"{k}: {self._serialize_bool(v)}")
+            elif self._should_emit_multiline(v, preserve_multiline):
+                lines.extend(self._serialize_multiline_scalar(k, v))
+            else:
+                safe = v_str.replace("'", "''")
+                lines.append(f"{k}: '{safe}'")
+        return lines
+
+    def _serialize_object_field_pair(
+        self,
+        spec: FieldSpec,
+        value: object,
+        preserve_multiline: bool = False,
+    ) -> list[str]:
+        """Serialize a single schematized field/value pair for an object-list item."""
+        if spec.type == "bool":
+            return [f"{spec.name}: {self._serialize_bool(value)}"]
+        if spec.type == "list":
+            if isinstance(value, list) and value:
+                lines = [f"{spec.name}:"]
+                lines.extend(f"  - {item_v}" for item_v in value)
+                return lines
+            return []
+        if self._should_emit_multiline(value, preserve_multiline):
+            return self._serialize_multiline_scalar(spec.name, value)
+        return [f"{spec.name}: {self._serialize_scalar(spec, value)}"]
+
+    def _serialize_object(
+        self,
+        item: dict,
+        item_schema: FrontmatterSchema | None,
+        preserve_multiline: bool = False,
+    ) -> list[str]:
+        """Serialize one object-list item to YAML lines (without leading ``  - ``)."""
+        if item_schema is None:
+            return self._serialize_object_unschematized(item, preserve_multiline)
+
+        pairs = [
+            (spec, item.get(spec.name))
+            for spec in item_schema.fields
+            if item.get(spec.name) is not None
+        ]
+        ordered_lines: list[str] = []
+        for spec, value in pairs:
+            ordered_lines.extend(self._serialize_object_field_pair(spec, value, preserve_multiline))
+        return ordered_lines
+
+    def _append_object_list_items(
+        self,
+        lines: list[str],
+        value: list,
+        item_schema: FrontmatterSchema | None,
+        preserve_multiline: bool = False,
+    ) -> None:
+        """Append object-list items to lines with proper YAML indentation."""
+        for item in value:
+            if not isinstance(item, dict):
+                continue
+            obj_lines = self._serialize_object(
+                item,
+                item_schema,
+                preserve_multiline=preserve_multiline,
+            )
+            for i, obj_line in enumerate(obj_lines):
+                prefix = "  - " if i == 0 else "    "
+                lines.append(f"{prefix}{obj_line}")
+
+    def _append_raw_field(self, lines: list[str], name: str, value: object) -> None:
+        """Append a raw YAML field value without additional serialization."""
+        raw_str = str(value).strip() if value is not None else ""
+        if raw_str:
+            lines.append(f"{name}:")
+            for raw_line in str(value).split("\n"):
+                lines.append(raw_line)
+
+    def _append_field_by_type(
+        self,
+        lines: list[str],
+        spec: FieldSpec,
+        value: object,
+        preserve_multiline: bool = False,
+    ) -> None:
+        """Dispatch field rendering by type."""
+        if spec.type == "bool":
+            lines.append(f"{spec.name}: {self._serialize_bool(value)}")
+            return
+        if spec.type == "list":
+            if isinstance(value, list) and value:
+                lines.append(f"{spec.name}:")
+                for item in value:
+                    lines.append(f"  - {item}")
+            return
+        if spec.type == "object-list":
+            if isinstance(value, list) and value:
+                lines.append(f"{spec.name}:")
+                self._append_object_list_items(
+                    lines,
+                    value,
+                    spec.item_schema,
+                    preserve_multiline=preserve_multiline,
+                )
+            return
+        if spec.type == "raw":
+            self._append_raw_field(lines, spec.name, value)
+            return
+        if self._should_emit_multiline(value, preserve_multiline):
+            lines.extend(self._serialize_multiline_scalar(spec.name, value))
+        else:
+            lines.append(f"{spec.name}: {self._serialize_scalar(spec, value)}")
+
+    def serialize(
+        self,
+        meta: dict,
+        schema: FrontmatterSchema,
+        preserve_multiline: bool = False,
+    ) -> str:
+        """Serialize metadata into a VS Code frontmatter block.
+
+        Args:
+            meta: Input metadata values to serialize.
+            schema: Ordered frontmatter schema that filters and formats fields.
+            preserve_multiline: When ``True``, emit long strings as folded YAML
+                block scalars where appropriate.
+
+        Returns:
+            A YAML frontmatter block including opening and closing ``---`` lines.
+        """
+        lines = ["---"]
+        for spec in schema.fields:
+            value = meta.get(spec.name)
+            if value is None:
+                continue
+            self._append_field_by_type(lines, spec, value, preserve_multiline)
+        lines.append("---")
+        lines.append("")
+        return "\n".join(lines)

vstack/instructions/__init__.py

@@ -0,0 +1,5 @@
+"""Package initialization for vstack.instructions."""
+
+from vstack.instructions.generator import InstructionGenerator
+
+__all__ = ["InstructionGenerator"]

vstack/instructions/config.py

@@ -0,0 +1,21 @@
+"""Instruction artifact type configuration."""
+
+from vstack.artifacts.config import INSTRUCTION_SCHEMA, ArtifactTypeConfig
+from vstack.instructions.constants import (
+    INSTRUCTION_OUTPUT_SUBDIR,
+    INSTRUCTION_OUTPUT_SUFFIX,
+    INSTRUCTION_TEMPLATES_SUBDIR,
+)
+
+INSTRUCTION_TYPE = ArtifactTypeConfig(
+    type_name="instruction",
+    templates_dir=INSTRUCTION_TEMPLATES_SUBDIR,
+    output_subdir=INSTRUCTION_OUTPUT_SUBDIR,
+    output_pattern=f"{{name}}{INSTRUCTION_OUTPUT_SUFFIX}",
+    add_frontmatter=True,
+    artifact_is_dir=False,
+    partials_subdir=None,
+    auto_gen_footer=True,
+    fail_on_unresolved=False,
+    frontmatter_schema=INSTRUCTION_SCHEMA,
+)

vstack/instructions/constants.py

@@ -0,0 +1,9 @@
+"""Constants for instruction template and output locations."""
+
+from vstack.constants import TEMPLATES_ROOT
+
+INSTRUCTION_OUTPUT_SUFFIX = ".instructions.md"
+INSTRUCTION_TEMPLATES_SUBDIR = "instructions"
+INSTRUCTION_OUTPUT_SUBDIR = "instructions"
+
+INSTRUCTION_TEMPLATES_DIR = TEMPLATES_ROOT / INSTRUCTION_TEMPLATES_SUBDIR

vstack/instructions/generator.py

@@ -0,0 +1,13 @@
+"""Thin instruction generator wrapper over ``GenericArtifactGenerator``."""
+
+from vstack.artifacts.generator import GenericArtifactGenerator
+from vstack.constants import TEMPLATES_ROOT
+from vstack.instructions.config import INSTRUCTION_TYPE
+
+
+class InstructionGenerator(GenericArtifactGenerator):
+    """Generate instruction artifacts using the built-in instruction configuration."""
+
+    def __init__(self) -> None:
+        """Create an instruction generator bound to the built-in template root."""
+        super().__init__(INSTRUCTION_TYPE, TEMPLATES_ROOT)

vstack/main.py

@@ -0,0 +1,71 @@
+"""CLI entrypoint and command dispatch helpers."""
+
+from __future__ import annotations
+
+import sys
+
+from vstack.cli.commands import CommandLineInterface
+from vstack.cli.parser import CommandLineParser
+from vstack.constants import TEMPLATES_ROOT
+
+_GLOBAL_SUPPORTED_TYPES = ["agent", "instruction", "prompt", "skill"]
+
+
+def _resolve_only_for_scope(args: object) -> list[str] | None:
+    """Resolve the active artifact-type filter for the parsed CLI arguments.
+
+    Args:
+        args: Parsed CLI arguments object, typically from ``argparse``.
+
+    Returns:
+        The explicit ``--only`` filter for the active scope, the default
+        global-profile artifact set, or ``None`` when no filter applies.
+    """
+    requested_only = getattr(args, "only", None)
+    if not getattr(args, "use_global", False):
+        return requested_only
+
+    if requested_only is None:
+        return list(_GLOBAL_SUPPORTED_TYPES)
+
+    disallowed = [t for t in requested_only if t not in _GLOBAL_SUPPORTED_TYPES]
+    if disallowed:
+        print(
+            "ERROR: --global supports only agents, prompts, and instructions. "
+            f"Unsupported type(s): {', '.join(disallowed)}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    return requested_only
+
+
+def main() -> None:
+    """Parse CLI arguments and dispatch the selected top-level command."""
+    cli_parser = CommandLineParser()
+    parser = cli_parser.build()
+    args = parser.parse_args()
+    cli = CommandLineInterface(templates_root=TEMPLATES_ROOT)
+
+    if args.command == "validate":
+        sys.exit(cli.validate(only=getattr(args, "only", None)))
+
+    install_dir = cli_parser.resolve_targets(args)
+    only = _resolve_only_for_scope(args) if args.command in {"install", "verify"} else None
+    dispatch = {
+        "verify": lambda: cli.verify(
+            install_dir=install_dir,
+            source=getattr(args, "source", True),
+            output=getattr(args, "output", True),
+            only=only,
+        ),
+        "install": lambda: cli.install(
+            install_dir,
+            only=only,
+            force=getattr(args, "force", False),
+            update=getattr(args, "update", False),
+            dry_run=getattr(args, "dry_run", False),
+        ),
+        "uninstall": lambda: cli.uninstall(install_dir),
+    }
+    sys.exit(dispatch[args.command]())

vstack/models.py

@@ -0,0 +1,35 @@
+"""Shared validation result models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CheckMessage:
+    """Represent a single validation message with a pass/fail level."""
+
+    level: str  # "pass" | "fail"
+    message: str
+
+
+@dataclass
+class ValidationResult:
+    """Store validation messages and expose aggregate result helpers."""
+
+    messages: list[CheckMessage] = field(default_factory=list)
+
+    @property
+    def passes(self) -> int:
+        """Return the number of passing validation messages."""
+        return sum(1 for m in self.messages if m.level == "pass")
+
+    @property
+    def failures(self) -> int:
+        """Return the number of failing validation messages."""
+        return sum(1 for m in self.messages if m.level == "fail")
+
+    @property
+    def ok(self) -> bool:
+        """Return ``True`` when the validation result contains no failures."""
+        return self.failures == 0

vstack/prompts/__init__.py

@@ -0,0 +1,5 @@
+"""Package initialization for vstack.prompts."""
+
+from vstack.prompts.generator import PromptGenerator
+
+__all__ = ["PromptGenerator"]

vstack/prompts/config.py

@@ -0,0 +1,21 @@
+"""Prompt artifact type configuration."""
+
+from vstack.artifacts.config import PROMPT_SCHEMA, ArtifactTypeConfig
+from vstack.prompts.constants import (
+    PROMPT_OUTPUT_SUBDIR,
+    PROMPT_OUTPUT_SUFFIX,
+    PROMPT_TEMPLATES_SUBDIR,
+)
+
+PROMPT_TYPE = ArtifactTypeConfig(
+    type_name="prompt",
+    templates_dir=PROMPT_TEMPLATES_SUBDIR,
+    output_subdir=PROMPT_OUTPUT_SUBDIR,
+    output_pattern=f"{{name}}{PROMPT_OUTPUT_SUFFIX}",
+    add_frontmatter=True,
+    artifact_is_dir=False,
+    partials_subdir=None,
+    auto_gen_footer=True,
+    fail_on_unresolved=False,
+    frontmatter_schema=PROMPT_SCHEMA,
+)

vstack/prompts/constants.py

@@ -0,0 +1,9 @@
+"""Constants for prompt template and output locations."""
+
+from vstack.constants import TEMPLATES_ROOT
+
+PROMPT_OUTPUT_SUFFIX = ".prompt.md"
+PROMPT_TEMPLATES_SUBDIR = "prompts"
+PROMPT_OUTPUT_SUBDIR = "prompts"
+
+PROMPT_TEMPLATES_DIR = TEMPLATES_ROOT / PROMPT_TEMPLATES_SUBDIR

vstack/prompts/generator.py

@@ -0,0 +1,13 @@
+"""Thin prompt generator wrapper over ``GenericArtifactGenerator``."""
+
+from vstack.artifacts.generator import GenericArtifactGenerator
+from vstack.constants import TEMPLATES_ROOT
+from vstack.prompts.config import PROMPT_TYPE
+
+
+class PromptGenerator(GenericArtifactGenerator):
+    """Generate prompt artifacts using the built-in prompt configuration."""
+
+    def __init__(self) -> None:
+        """Create a prompt generator bound to the built-in template root."""
+        super().__init__(PROMPT_TYPE, TEMPLATES_ROOT)

vstack/skills/__init__.py

@@ -0,0 +1,5 @@
+"""Package initialization for vstack.skills."""
+
+from vstack.skills.generator import SkillGenerator
+
+__all__ = ["SkillGenerator"]

vstack/skills/config.py

@@ -0,0 +1,58 @@
+"""Skill artifact type configuration and frontmatter schema.
+
+Defines the :data:`SKILL_SCHEMA` (which frontmatter fields a ``SKILL.md`` file
+uses) and the :data:`SKILL_TYPE` descriptor that configures the generator for
+the ``skills`` artifact family.
+"""
+
+from __future__ import annotations
+
+from vstack.artifacts.config import ArtifactTypeConfig
+from vstack.frontmatter import FieldSpec, FrontmatterSchema
+from vstack.skills.constants import (
+    SKILL_OUTPUT_SUBDIR,
+    SKILL_TEMPLATES_SUBDIR,
+    SKILL_TMPL_NAME,
+)
+
+#: Fields recognised in VS Code Agent Skill files (``SKILL.md``).
+SKILL_SCHEMA = FrontmatterSchema(
+    [
+        FieldSpec(
+            "name",
+            required=True,
+            quoted=False,
+            max_length=64,
+            pattern=r"[a-z0-9]+(?:-[a-z0-9]+)*",
+        ),
+        FieldSpec("description", required=True, max_length=1024, normalize_whitespace=True),
+        FieldSpec("license", max_length=256),
+        FieldSpec("compatibility", max_length=500, normalize_whitespace=True),
+        # Agent Skills spec: arbitrary key/value mapping. We preserve this as raw YAML.
+        FieldSpec("metadata", type="raw"),
+        FieldSpec("argument-hint"),
+        FieldSpec("user-invocable", type="bool"),
+        FieldSpec("disable-model-invocation", type="bool"),
+    ]
+)
+
+#: Type descriptor for the ``skills`` artifact family.
+SKILL_TYPE = ArtifactTypeConfig(
+    type_name="skill",
+    templates_dir=SKILL_TEMPLATES_SUBDIR,
+    output_subdir=SKILL_OUTPUT_SUBDIR,
+    output_pattern="{name}/SKILL.md",
+    add_frontmatter=True,
+    artifact_is_dir=True,
+    partials_subdir="_partials",
+    auto_gen_footer=True,
+    placeholders={
+        "SKILL_CONTEXT": "skill-context.md",
+        "BASE_BRANCH": "base-branch.md",
+        "RUN_TESTS": "run-tests.md",
+        "OBSERVABILITY_CHECKLIST": "observability-checklist.md",
+    },
+    fail_on_unresolved=True,
+    template_filename=SKILL_TMPL_NAME,
+    frontmatter_schema=SKILL_SCHEMA,
+)

vstack/skills/constants.py

@@ -0,0 +1,17 @@
+"""Constants for skill template and partial locations."""
+
+from __future__ import annotations
+
+from vstack.constants import TEMPLATES_ROOT
+
+#: Source template filename.
+SKILL_TMPL_NAME = "template.md"
+
+#: Subdirectory name under ``templates/`` holding skill source templates.
+SKILL_TEMPLATES_SUBDIR = "skills"
+
+#: Subdirectory name under the install root (e.g. ``.github/``) for skill output.
+SKILL_OUTPUT_SUBDIR = "skills"
+
+SKILLS_TEMPLATES_DIR = TEMPLATES_ROOT / SKILL_TEMPLATES_SUBDIR
+SKILLS_PARTIALS_DIR = TEMPLATES_ROOT / SKILL_TEMPLATES_SUBDIR / "_partials"

vstack/skills/generator.py

@@ -0,0 +1,20 @@
+"""SkillGenerator — thin wrapper around GenericArtifactGenerator for skills.
+
+Import :class:`SkillGenerator` to get a generator pre-configured for the
+``skills`` artifact type.  All behaviour is inherited from
+:class:`~vstack.artifacts.generator.GenericArtifactGenerator`.
+"""
+
+from __future__ import annotations
+
+from vstack.artifacts.generator import GenericArtifactGenerator
+from vstack.constants import TEMPLATES_ROOT
+from vstack.skills.config import SKILL_TYPE
+
+
+class SkillGenerator(GenericArtifactGenerator):
+    """Generate skill artifacts using the built-in skill type configuration."""
+
+    def __init__(self) -> None:
+        """Create a skill generator bound to the built-in template root."""
+        super().__init__(SKILL_TYPE, TEMPLATES_ROOT)