feat: improve stolt/skill-md integration

Author: raphaelstolt

.github/workflows/test.yml

@@ -14,7 +14,6 @@ jobs:
     strategy:
       matrix:
         php:
-          - "8.2"
           - "8.3"
           - "8.4"
           - "8.5"

CHANGELOG.md

@@ -7,6 +7,12 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 ## [Unreleased]
 
+## [v0.1.0] - 2026-05-16
+
+### Improved
+
+- Improved the integrating of the [stolt/skill-md](https://github.com/raphaelstolt/skill-md/) package.
+
 ## [v0.0.5] - 2026-05-13
 
 ### Added
@@ -35,8 +41,9 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 
 - Initial release.
 
-[Unreleased]: https://github.com/raphaelstolt/skill-validator/compare/v0.0.5...HEAD
+[Unreleased]: https://github.com/raphaelstolt/skill-validator/compare/v0.1.0...HEAD
 
+[v0.1.0]: https://github.com/raphaelstolt/skill-validator/compare/v0.0.5...v0.1.0
 [v0.0.5]: https://github.com/raphaelstolt/skill-validator/compare/v0.0.4...v0.0.5
 [v0.0.4]: https://github.com/raphaelstolt/skill-validator/compare/v0.0.3...v0.0.4
 [v0.0.3]: https://github.com/raphaelstolt/skill-validator/compare/v0.0.2...v0.0.3

README.md

@@ -19,7 +19,11 @@ composer require stolt/skill-validator
 
 ## Usage
 
-The validator can validate either existing `SKILL.md` files or raw `SKILL.md` content.
+The `SkillMd` class from the [stolt/skill-md](https://github.com/raphaelstolt/skill-md/) package is the primary
+abstraction for a validated skill: every valid result exposes a `SkillMd` instance, and the validator also accepts
+`SkillMd` instances directly as input.
+
+The validator can validate existing `SKILL.md` files, raw `SKILL.md` content, or `SkillMd` instances.
 
 ### Validating a `SKILL.md` file
 
@@ -60,14 +64,31 @@ $validator = new Validator();
 $result = $validator->validateContent('raw-skill-content');
 ```
 
+### Validating a `SkillMd` instance
+
+```php
+use Stolt\Ai\Skill\Validator;
+use Stolt\Ai\SkillMd;
+
+$skillMd = SkillMd::create(
+    'code-review',
+    'Review code changes and provide actionable feedback.',
+    "# Code review\n\nReview the changed files and report issues.",
+    ['tags' => ['php', 'review'], 'version' => '1.0.0']
+);
+
+$validator = new Validator();
+$result = $validator->validateSkillMd($skillMd);
+```
+
 > [!TIP]
-> The `validate` alias method accepts either a file path, directory path, or raw content and delegates to the
-> appropriate method automatically.
+> The `validate` alias method accepts a file path, directory path, raw content, or a `SkillMd` instance and delegates
+> to the appropriate method automatically.
 
 ### Accessing validation results and metadata
 
-Validation returns a `Stolt\Ai\Skill\ValidationResult` object. When the `SKILL.md` content contains the required `name`
-and `description` fields, the parsed metadata is exposed as a `Stolt\Ai\Skill\Metadata` object.
+Validation returns a `Stolt\Ai\Skill\ValidationResult` object. When the `SKILL.md` content is valid, a `SkillMd`
+instance is available directly. The parsed metadata is also accessible as a `Stolt\Ai\Skill\Metadata` object.
 
 ```php
 use Stolt\Ai\Skill\Validator;
@@ -78,28 +99,30 @@ $result = $validator->validateContent('raw-skill-content');
 if ($result->isInvalid()) {
     foreach ($result->errors() as $error) {
         echo $error . PHP_EOL;
-    } 
+    }
     // Raw metadata can still be inspected when parsing succeeded but validation failed.
     $rawMetadata = $result->rawMetadata();
     exit(1);
-} 
+}
 
-$metadata = $result->metadata();
+// Primary SkillMd abstraction — available on every valid result.
+$skillMd = $result->skillMd();  // returns ?SkillMd (null when invalid)
 
-if ($metadata === null) {
-    throw new RuntimeException('Expected validated SKILL.md metadata.');
-}
+// Or assert the SkillMd directly, which throws a LogicException when the result is invalid.
+$skillMd = $result->toSkillMd();
 
-// Required SKILL.md metadata fields.
-$name = $metadata->name();
-$description = $metadata->description();
+// Use the SkillMd instance.
+$name        = $skillMd->name();
+$description = $skillMd->description();
+$body        = $skillMd->body();
+$tags        = $skillMd->tags();
+$version     = $skillMd->version();
 
-// Optional SKILL.md metadata fields.
-$version = $metadata->version();
-$tags = $metadata->tags();
-$allowedTools = $metadata->get('allowed-tools', []);
-$model = $metadata->get('model');
-$effort = $metadata->get('effort');
+// Metadata object for field access with defaults.
+$metadata    = $result->metadata();
+$allowedTools = $metadata?->get('allowed-tools', []);
+$model       = $metadata?->get('model');
+$effort      = $metadata?->get('effort');
 
 // Markdown instructions after the YAML frontmatter.
 $instructions = $result->body();
@@ -110,20 +133,28 @@ $arrayResult = $result->toArray();
 echo sprintf('Skill "%s" is valid: %s', $name, $description) . PHP_EOL;
 ```
 
-For an actual integration, the project [list-skills-command](https://github.com/raphaelstolt/list-skills-command) can also be consolidated.
+### Round-tripping between content and `SkillMd`
 
-> [!TIP]
-> As of version `0.0.5` you can use the `toSkillMd()` method to collect a populated `SkillMd` instance of the [stolt/skill-md](https://github.com/raphaelstolt/skill-md/) package.
+Because `validateSkillMd()` accepts a `SkillMd` instance and `toSkillMd()` returns one, validation results and
+`SkillMd` objects round-trip cleanly:
 
 ```php
 use Stolt\Ai\Skill\Validator;
 
 $validator = new Validator();
-$result = $validator->validateContent('raw-skill-content');
 
+// Parse and validate raw content.
+$result = $validator->validateContent($rawContent);
+
+// Obtain the primary SkillMd abstraction.
 $skillMd = $result->toSkillMd();
+
+// Re-validate the SkillMd — e.g. after modifying it.
+$revalidated = $validator->validateSkillMd($skillMd);
 ```
 
+For an actual integration, the project [list-skills-command](https://github.com/raphaelstolt/list-skills-command) can also be consolidated.
+
 ## Validation rules
 
 The validator checks that a `SKILL.md` document:

src/ValidationResult.php

@@ -18,6 +18,7 @@ private function __construct(
         private ?Metadata $metadata,
         private array     $rawMetadata,
         private string    $body,
+        private ?SkillMd  $skillMd = null,
     ) {
     }
 
@@ -28,7 +29,13 @@ public static function valid(Metadata $metadata, string $body): self
             [],
             $metadata,
             $metadata->toArray(),
-            $body
+            $body,
+            SkillMd::create(
+                $metadata->name(),
+                $metadata->description(),
+                $body,
+                $metadata->additionalFields()
+            )
         );
     }
 
@@ -105,14 +112,20 @@ public function body(): string
         return $this->body;
     }
 
+    public function skillMd(): ?SkillMd
+    {
+        return $this->skillMd;
+    }
+
     public function toSkillMd(): SkillMd
     {
-        return SkillMd::create(
-            $this->metadata?->get('name'),
-            $this->metadata?->get('description'),
-            $this->body(),
-            $this->metadata?->toArray() ?? []
-        );
+        if ($this->skillMd === null) {
+            throw new \LogicException(
+                'Cannot convert an invalid ValidationResult to a SkillMd instance.'
+            );
+        }
+
+        return $this->skillMd;
     }
 
     /**

src/Validator.php

@@ -4,6 +4,8 @@
 
 namespace Stolt\Ai\Skill;
 
+use Stolt\Ai\SkillMd;
+
 final class Validator
 {
     private const MAX_NAME_LENGTH = 64;
@@ -75,8 +77,12 @@ public function validateFromDirectory(string $directory): array
     /**
      * @return ValidationResult|array<string, ValidationResult>
      */
-    public function validate(string $input): ValidationResult|array
+    public function validate(string|SkillMd $input): ValidationResult|array
     {
+        if ($input instanceof SkillMd) {
+            return $this->validateSkillMd($input);
+        }
+
         if (\is_dir($input)) {
             return $this->validateFromDirectory($input);
         }
@@ -88,6 +94,11 @@ public function validate(string $input): ValidationResult|array
         return $this->validateContent($input);
     }
 
+    public function validateSkillMd(SkillMd $skillMd): ValidationResult
+    {
+        return $this->validateContent($skillMd->toMarkdown());
+    }
+
     public function validateFile(string $skillFile): ValidationResult
     {
         if (\is_file($skillFile) === false) {