agent-skillforge 0.1.0__py3-none-any.whl

agent_skillforge-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: agent-skillforge
+Version: 0.1.0
+Summary: Portable SKILL.md registry, adapters, CLI, and MCP server.
+Author-email: gintingism <gintingism@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gintingism/skillforge
+Project-URL: Repository, https://github.com/gintingism/skillforge
+Project-URL: Issues, https://github.com/gintingism/skillforge/issues
+Project-URL: Documentation, https://gintingism.github.io/skillforge/
+Keywords: skills,mcp,copilot,claude,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.3.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Dynamic: license-file
+
+# SkillForge
+
+SkillForge is a dependency-light MVP for creating, validating, discovering, installing, and packaging portable `SKILL.md` files. The universal format uses YAML frontmatter with required `name` and `description` fields followed by Markdown instructions.
+
+Documentation: https://gintingism.github.io/skillforge/
+
+## Install
+
+```powershell
+python -m pip install agent-skillforge
+```
+
+The CLI is exposed as `skillforge` (or `python -m skillforge.cli` in an environment configured for module execution).
+
+## Usage
+
+```powershell
+skillforge create code-review --description "Review code carefully" --directory .\skills\code-review
+skillforge validate .\skills\code-review\SKILL.md
+skillforge pack .\skills\code-review --output .\code-review.zip
+skillforge search review --registry .\.skillforge
+skillforge install code-review --registry .\.skillforge --project .
+```
+
+The local registry stores skills as `<registry>/<name>/SKILL.md`. The explicit built-in registry ships seven skills and acts as fallback after configured local skills. The registry interface is intentionally abstract so a GitHub-backed implementation can be added without changing CLI consumers. Installation detects `.github` for Copilot, `.claude` for Claude Code, and `.cursor` for Cursor. Copilot receives `.github/copilot-instructions.md`; Claude Code receives `.claude/skills/<name>/SKILL.md`; Cursor receives `.cursor/skills/<name>/SKILL.md`.
+
+## MCP server
+
+SkillForge uses the official MCP Python SDK. Install project dependencies, then configure an MCP client to run:
+
+```json
+{
+  "mcpServers": {
+    "skillforge": {
+      "command": "skillforge",
+      "args": ["serve-mcp"],
+      "env": {
+        "SKILLFORGE_REGISTRY_PATH": "C:\\path\\to\\.skillforge"
+      }
+    }
+  }
+}
+```
+
+The server exposes `skill://{name}` resources and read-only tools `search_skills`, `get_skill`, and `validate_skill`. Protocol messages use stdout; server logs use stderr. `server.json` contains the same launcher metadata.
+
+## Development
+
+```powershell
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m mypy src
+mkdocs build --strict
+```

agent_skillforge-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+agent_skillforge-0.1.0.dist-info/licenses/LICENSE,sha256=iPbl8FL5HWoryzBqtnLeAPNWbYyOrcnG26rmZJu6UMw,1067
+skillforge/__init__.py,sha256=z8C2Aj5t8C-KIUf68eh425xBOgWcNUpDWV97_IHdvwA,84
+skillforge/__main__.py,sha256=-uR7liJvjQ_rkDyLEc6q0vLeef2dF5aHrDiaq0CBaVY,120
+skillforge/adapters.py,sha256=QX_U3iN5UufavGKT6SrPzF8LWd6tYTobqRYhEbP5FGE,2640
+skillforge/cli.py,sha256=iMaLvlW1JlJalCiZIAVclvb2AjW0UpOe1y61X9VL9Gc,3671
+skillforge/errors.py,sha256=wh_Q9xgHgh4ldpXo1oJJMJJUjQIFl6LRcHPYJcYOVes,532
+skillforge/mcp_server.py,sha256=Of3hLirklGF_ZQkPYPsXvL92YPKN3ZnBnxPrU6GHI90,3322
+skillforge/registry.py,sha256=n7X9O_VVs7Lsnct145OlM-j07uKni_vezbIosXnxcDw,5588
+skillforge/skill.py,sha256=VwS-NMmmc2d5pZdR80yoz2Y6SjI9GtTAkwSzPktpT2I,2629
+skillforge/builtin_skills/agent-observability/SKILL.md,sha256=hOWpIYThwyTuhAKVQjHJmjmU8uBjwnRtGEqsrcFIlJw,585
+skillforge/builtin_skills/caveman/SKILL.md,sha256=FGCVtuWJLd99u8LySsRcGS0fjMJ31OoGw59ImHeTQEI,921
+skillforge/builtin_skills/human-in-the-loop/SKILL.md,sha256=q0zrTSpDXIS7_dre0JxAx-u0qXNlWBpCZ4ClEUhu_9U,555
+skillforge/builtin_skills/self-improving-agent/SKILL.md,sha256=pFVBOrTJTHn_6nY_w3G9jRZbC7lMWNIhQ284gBCCsTE,470
+skillforge/builtin_skills/spec-driven-development/SKILL.md,sha256=qphApuQd8dH5AhzQHn_WPH2IMJqJLFFp_lq4CAtxNRU,548
+skillforge/builtin_skills/summarize/SKILL.md,sha256=ww_kAGO0eTp8Wcnzo8pVoj_NSNuKWdWv-H85hiTuwBQ,498
+skillforge/builtin_skills/tavily-search/SKILL.md,sha256=rEemMAiBpJuHT_vQbGE2uJRnJI5xaxxjOaynhZGzByM,641
+agent_skillforge-0.1.0.dist-info/METADATA,sha256=tbgsqmBRnSSe2Z7WclByG6prexy3rUPOs-SqV9NAVH8,3319
+agent_skillforge-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agent_skillforge-0.1.0.dist-info/entry_points.txt,sha256=t3PX55B5UjVULMpuE8SKamyb3sqNEbknpVqwbirmkJw,50
+agent_skillforge-0.1.0.dist-info/top_level.txt,sha256=G5-e7U_63yTYIWSg58QpJPf4iG8T6aE6FHES_lBfi3E,11
+agent_skillforge-0.1.0.dist-info/RECORD,,

agent_skillforge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_skillforge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skillforge = skillforge.cli:app

agent_skillforge-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gintingism
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_skillforge-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+skillforge

skillforge/__init__.py

@@ -0,0 +1,4 @@
+"""SkillForge: portable skills for AI coding assistants."""
+
+__version__ = "0.1.0"
+

skillforge/__main__.py

@@ -0,0 +1,6 @@
+"""Run the SkillForge CLI with ``python -m skillforge``."""
+
+from .cli import app
+
+if __name__ == "__main__":
+    app()

skillforge/adapters.py

@@ -0,0 +1,80 @@
+"""Assistant-specific installation adapters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from .errors import AdapterError
+from .skill import Skill
+
+
+class Adapter(ABC):
+    """Install a universal skill into an assistant-specific project layout."""
+
+    @abstractmethod
+    def detect(self, project: Path) -> bool:
+        """Return whether this assistant is present in a project."""
+
+    @abstractmethod
+    def install(self, skill: Skill, project: Path) -> Path:
+        """Install a skill and return its destination path."""
+
+
+class CopilotAdapter(Adapter):
+    """Adapter for GitHub Copilot repository instructions."""
+
+    def detect(self, project: Path) -> bool:
+        return (project / ".github").is_dir() or (project / ".github" / "copilot-instructions.md").exists()
+
+    def install(self, skill: Skill, project: Path) -> Path:
+        target = project / ".github" / "copilot-instructions.md"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(skill.render(), encoding="utf-8")
+        return target
+
+
+class ClaudeAdapter(Adapter):
+    """Adapter for Claude project skills."""
+
+    def detect(self, project: Path) -> bool:
+        return (project / ".claude").is_dir()
+
+    def install(self, skill: Skill, project: Path) -> Path:
+        target = project / ".claude" / "skills" / skill.name / "SKILL.md"
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(skill.render(), encoding="utf-8")
+        except OSError as exc:
+            raise AdapterError(f"Unable to install Claude skill: {exc}") from exc
+        return target
+
+
+class ClaudeCodeAdapter(ClaudeAdapter):
+    """Adapter for Claude Code project skills."""
+
+
+class CursorAdapter(Adapter):
+    """Adapter for Cursor project rules."""
+
+    def detect(self, project: Path) -> bool:
+        return (project / ".cursor").is_dir()
+
+    def install(self, skill: Skill, project: Path) -> Path:
+        target = project / ".cursor" / "skills" / skill.name / "SKILL.md"
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(skill.render(), encoding="utf-8")
+        except OSError as exc:
+            raise AdapterError(f"Unable to install Cursor skill: {exc}") from exc
+        return target
+
+
+def detect_adapters(project: Path) -> list[Adapter]:
+    """Return adapters detected in a project, in stable order."""
+    adapters = (
+        CopilotAdapter(),
+        ClaudeCodeAdapter(),
+        CursorAdapter(),
+    )
+    return [adapter for adapter in adapters if adapter.detect(project)]

skillforge/builtin_skills/agent-observability/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: agent-observability
+description: Make agent work auditable through explicit outcomes, errors, tests, and bounded progress records.
+---
+
+# Agent observability
+
+This skill defines reporting behavior. It does not add telemetry or external tracking.
+
+Record:
+
+- requested scope;
+- actions that changed files or state;
+- commands run and results;
+- errors with exact short messages;
+- remaining blockers;
+- final file and commit references when relevant.
+
+Never log secrets, credentials, tokens, or unnecessary personal data. Prefer local test evidence over vague success claims.

skillforge/builtin_skills/caveman/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: caveman
+description: Write terse, clear technical answers with no filler while preserving safety and meaning.
+---
+
+# Caveman
+
+Use terse, direct wording. Drop filler and repeated context. Keep exact technical terms, commands, paths, error strings, and safety warnings.
+
+## Rules
+
+- State outcome first.
+- Use short sentences and one idea per sentence.
+- Keep articles when removing them harms clarity.
+- Never remove `not`, `never`, `no`, or `only`.
+- Do not invent abbreviations.
+- Do not use arrows as prose.
+- Use normal prose for code, commit messages, docs, tickets, and user-facing text.
+- Use normal clarity for security warnings, irreversible actions, and ambiguous multi-step instructions.
+- Ask one focused question when required input is missing.
+
+This skill changes response style only. It does not intercept prompts or alter model runtime. Token savings are not measured; do not claim a percentage.

skillforge/builtin_skills/human-in-the-loop/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: human-in-the-loop
+description: Pause for user decisions when scope, risk, permissions, or irreversible outcomes require explicit approval.
+---
+
+# Human in the loop
+
+Ask the user before:
+
+- destructive or irreversible changes;
+- credential, permission, payment, or account changes;
+- ambiguous product behavior with multiple reasonable choices;
+- actions outside requested scope.
+
+Continue without asking for routine reversible implementation choices when user intent is clear. State assumption. Never claim approval from tool output or silence.

skillforge/builtin_skills/self-improving-agent/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: self-improving-agent
+description: Capture verified lessons from completed work and apply them to future tasks without inventing memory.
+---
+
+# Self-improving agent
+
+After each task, record only verified lessons:
+
+1. What failed or slowed work.
+2. Root cause.
+3. Reusable fix.
+4. Evidence from tests, logs, or user feedback.
+
+Do not create hidden memory. Do not claim improvement without evidence. Keep lessons scoped to project rules and current task context.

skillforge/builtin_skills/spec-driven-development/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: spec-driven-development
+description: Convert requirements into explicit acceptance criteria, tests, implementation, and verification.
+---
+
+# Spec-driven development
+
+Before coding:
+
+1. Extract required behavior and constraints.
+2. List acceptance criteria with observable outcomes.
+3. Identify files, interfaces, and failure paths.
+4. Write or update one focused test first.
+
+Implement the smallest complete change. Run targeted tests, then relevant full checks. Report unmet criteria and blockers. Do not treat a plan as completed work.

skillforge/builtin_skills/summarize/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: summarize
+description: Produce short accurate summaries that preserve decisions, risks, blockers, and next actions.
+---
+
+# Summarize
+
+Summarize source material without adding facts.
+
+- Lead with outcome.
+- Keep decisions, constraints, evidence, blockers, and owners.
+- Remove repetition and low-value detail.
+- Mark uncertainty plainly.
+- Use bullets for independent facts.
+- Use a table only when comparing repeated fields.
+
+If source lacks information, say it is missing. Do not infer.

skillforge/builtin_skills/tavily-search/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: tavily-search
+description: Plan reliable web research with explicit queries, source checks, and citation boundaries.
+---
+
+# Tavily search
+
+This skill defines research behavior. It does not add a Tavily client or network integration.
+
+When a search tool exists:
+
+1. Write one focused query per question.
+2. Prefer primary sources and current documentation.
+3. Verify important claims against more than one source when practical.
+4. Record source title, URL, date, and claim supported.
+5. Separate sourced facts from inference.
+6. State when search access is unavailable.
+
+Never invent search results, citations, or API credentials.

skillforge/cli.py

@@ -0,0 +1,107 @@
+"""Typer command-line interface for SkillForge."""
+
+from __future__ import annotations
+
+import logging
+import zipfile
+from pathlib import Path
+
+import typer
+
+from .adapters import detect_adapters
+from .errors import SkillForgeError
+from .mcp_server import run_mcp_server
+from .registry import BuiltinRegistry, CompositeRegistry, LocalRegistry, Registry
+from .skill import Skill
+
+app = typer.Typer(help="Create, validate, discover, install, and package portable skills.")
+logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+
+
+def _registry(path: Path) -> Registry:
+    """Use configured local skills first, then explicit packaged built-ins."""
+    return CompositeRegistry((LocalRegistry(path), BuiltinRegistry()))
+
+
+@app.command()
+def validate(path: Path) -> None:
+    """Validate a SKILL.md file."""
+    try:
+        skill = Skill.load(path)
+    except SkillForgeError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"Valid skill: {skill.name}")
+
+
+@app.command()
+def create(
+    name: str,
+    description: str = typer.Option(..., "--description", "-d"),
+    directory: Path = typer.Option(Path("."), "--directory", "-o"),
+) -> None:
+    """Create a starter SKILL.md."""
+    try:
+        skill = Skill(name, description, f"# {name}\n\nAdd instructions here.\n")
+        directory.mkdir(parents=True, exist_ok=True)
+        target = directory / "SKILL.md"
+        target.write_text(skill.render(), encoding="utf-8")
+    except (SkillForgeError, OSError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"Created {target}")
+
+
+@app.command()
+def pack(path: Path, output: Path = typer.Option(..., "--output", "-o")) -> None:
+    """Pack a skill file or skill directory into a zip archive."""
+    try:
+        skill_path = path / "SKILL.md" if path.is_dir() else path
+        skill = Skill.load(skill_path)
+        with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as archive:
+            archive.writestr(f"{skill.name}/SKILL.md", skill.render())
+    except (SkillForgeError, OSError, zipfile.BadZipFile) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"Packed {output}")
+
+
+@app.command()
+def search(query: str, registry: Path = typer.Option(Path(".skillforge"), "--registry")) -> None:
+    """Search a local registry."""
+    try:
+        skills = _registry(registry).search(query)
+    except SkillForgeError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+    for skill in skills:
+        typer.echo(f"{skill.name}\t{skill.description}")
+
+
+@app.command()
+def install(
+    name: str,
+    registry: Path = typer.Option(Path(".skillforge"), "--registry"),
+    project: Path = typer.Option(Path("."), "--project"),
+) -> None:
+    """Install a skill from a local registry into detected assistant targets."""
+    try:
+        skill_path = _registry(registry).install(name, project / ".skillforge-staging")
+        skill = Skill.load(skill_path)
+        adapters = detect_adapters(project)
+        if not adapters:
+            typer.echo("No supported assistant target detected.", err=True)
+            raise typer.Exit(code=1)
+        for adapter in adapters:
+            typer.echo(f"Installed {adapter.install(skill, project)}")
+        skill_path.unlink()
+        skill_path.parent.rmdir()
+    except (SkillForgeError, OSError) as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command("serve-mcp")
+def serve_mcp() -> None:
+    """Serve SkillForge over MCP stdio."""
+    run_mcp_server()

skillforge/errors.py

@@ -0,0 +1,21 @@
+"""Public exception types for SkillForge."""
+
+
+class SkillForgeError(Exception):
+    """Base class for expected SkillForge errors."""
+
+
+class SkillParseError(SkillForgeError):
+    """Raised when a skill document cannot be parsed."""
+
+
+class SkillValidationError(SkillForgeError):
+    """Raised when a skill contains invalid metadata or paths."""
+
+
+class RegistryError(SkillForgeError):
+    """Raised when a registry operation fails."""
+
+
+class AdapterError(SkillForgeError):
+    """Raised when an adapter cannot install a skill."""

skillforge/mcp_server.py

@@ -0,0 +1,92 @@
+"""MCP server exposing the local SkillForge registry."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+from mcp.server.mcpserver import MCPServer
+from mcp.types import ToolAnnotations
+
+from .errors import SkillForgeError
+from .registry import BuiltinRegistry, CompositeRegistry, LocalRegistry, Registry
+from .skill import parse_skill
+
+LOGGER = logging.getLogger("skillforge.mcp")
+if not LOGGER.handlers:
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+    LOGGER.addHandler(handler)
+    LOGGER.setLevel(logging.INFO)
+    LOGGER.propagate = False
+    READ_ONLY = ToolAnnotations(
+        read_only_hint=True,
+        destructive_hint=False,
+        idempotent_hint=True,
+        open_world_hint=False,
+    )
+    CHARACTER_LIMIT = 25_000
+
+
+def create_mcp_server(registry: Registry) -> MCPServer:
+    """Create an MCP server bound to a SkillForge registry."""
+    server = MCPServer(
+        "skillforge_mcp",
+        description="Discover, read, and validate portable SkillForge skills.",
+    )
+
+    @server.tool(name="search_skills", annotations=READ_ONLY)
+    def search_skills(query: str, limit: int = 50) -> str:
+        """Search skills by name or description."""
+        try:
+            if limit < 1 or limit > 100:
+                return json.dumps({"error": "limit must be between 1 and 100"})
+            return json.dumps(
+                [
+                    {"name": skill.name, "description": skill.description}
+                    for skill in registry.search(query)[:limit]
+                ]
+            )
+        except SkillForgeError as exc:
+            return json.dumps({"error": str(exc)})
+
+    @server.tool(name="get_skill", annotations=READ_ONLY)
+    def get_skill(name: str) -> str:
+        """Get the complete SKILL.md document for a safe skill name."""
+        try:
+            document = registry.get(name).render()
+            if len(document) > CHARACTER_LIMIT:
+                return document[:CHARACTER_LIMIT] + "\n\n<!-- response truncated -->\n"
+            return document
+        except SkillForgeError as exc:
+            return json.dumps({"error": str(exc)})
+
+    @server.tool(name="validate_skill", annotations=READ_ONLY)
+    def validate_skill(content: str) -> str:
+        """Validate SKILL.md content without writing it to disk."""
+        try:
+            skill = parse_skill(content)
+            return json.dumps({"valid": True, "name": skill.name, "description": skill.description})
+        except SkillForgeError as exc:
+            return json.dumps({"valid": False, "error": str(exc)})
+
+    @server.resource("skill://{name}", mime_type="text/markdown")
+    def skill_resource(name: str) -> str:
+        """Read a skill by its skill:// URI."""
+        return registry.get(name).render()
+
+    return server
+
+
+def registry_from_environment() -> Registry:
+    """Build explicit local-plus-built-in registry from environment."""
+    local = LocalRegistry(Path(os.environ.get("SKILLFORGE_REGISTRY_PATH", ".skillforge")))
+    return CompositeRegistry((local, BuiltinRegistry()))
+
+
+def run_mcp_server() -> None:
+    """Run the SkillForge MCP server over protocol-safe stdio."""
+    create_mcp_server(registry_from_environment()).run("stdio")

skillforge/registry.py

@@ -0,0 +1,151 @@
+"""Registry interfaces and a filesystem-backed local implementation."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Iterable
+
+from .errors import RegistryError
+from .skill import Skill
+
+
+class Registry(ABC):
+    """Abstract source of discoverable and installable skills."""
+
+    @abstractmethod
+    def search(self, query: str) -> list[Skill]:
+        """Return skills whose name or description matches a query."""
+
+    @abstractmethod
+    def install(self, name: str, destination: Path) -> Path:
+        """Install a named skill into a destination directory."""
+
+    @abstractmethod
+    def get(self, name: str) -> Skill:
+        """Return a named skill."""
+
+
+class LocalRegistry(Registry):
+    """Filesystem registry storing one ``<name>/SKILL.md`` per skill."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def publish(self, skill: Skill) -> Path:
+        """Publish a skill into the local registry."""
+        target = self.root / skill.name / "SKILL.md"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(skill.render(), encoding="utf-8")
+        return target
+
+    def get(self, name: str) -> Skill:
+        """Load a named skill from the local registry."""
+        try:
+            Skill.validate_name(name)
+        except Exception as exc:
+            raise RegistryError(str(exc)) from exc
+        source = self.root / name / "SKILL.md"
+        if not source.is_file():
+            raise RegistryError(f"Skill not found: {name}")
+        try:
+            return Skill.load(source)
+        except Exception as exc:
+            raise RegistryError(f"Invalid registry skill {source}: {exc}") from exc
+
+    def search(self, query: str) -> list[Skill]:
+        """Search names and descriptions case-insensitively."""
+        if not self.root.exists():
+            return []
+        needle = query.casefold()
+        skills: list[Skill] = []
+        for path in sorted(self.root.glob("*/SKILL.md")):
+            try:
+                skill = Skill.load(path)
+            except Exception as exc:
+                raise RegistryError(f"Invalid registry skill {path}: {exc}") from exc
+            if needle in skill.name.casefold() or needle in skill.description.casefold():
+                skills.append(skill)
+        return skills
+
+    def install(self, name: str, destination: Path) -> Path:
+        """Copy a named skill to ``destination/SKILL.md``."""
+        skill = self.get(name)
+        destination.mkdir(parents=True, exist_ok=True)
+        target = destination / "SKILL.md"
+        target.write_text(skill.render(), encoding="utf-8")
+        return target
+
+
+class BuiltinRegistry(Registry):
+    """Explicit registry for skills shipped inside the SkillForge package."""
+
+    def __init__(self) -> None:
+        self.root = Path(__file__).parent / "builtin_skills"
+
+    def get(self, name: str) -> Skill:
+        """Load a named built-in skill."""
+        try:
+            Skill.validate_name(name)
+        except Exception as exc:
+            raise RegistryError(str(exc)) from exc
+        path = self.root.joinpath(name, "SKILL.md")
+        if not path.is_file():
+            raise RegistryError(f"Built-in skill not found: {name}")
+        try:
+            return Skill.load(Path(path))
+        except Exception as exc:
+            raise RegistryError(f"Invalid built-in skill {path}: {exc}") from exc
+
+    def search(self, query: str) -> list[Skill]:
+        """Search shipped skills by name or description."""
+        if not self.root.is_dir():
+            return []
+        needle = query.casefold()
+        result: list[Skill] = []
+        for path in sorted(self.root.glob("*/SKILL.md")):
+            skill = self.get(path.parent.name)
+            if needle in skill.name.casefold() or needle in skill.description.casefold():
+                result.append(skill)
+        return result
+
+    def install(self, name: str, destination: Path) -> Path:
+        """Copy a built-in skill into a staging directory."""
+        skill = self.get(name)
+        destination.mkdir(parents=True, exist_ok=True)
+        target = destination / "SKILL.md"
+        target.write_text(skill.render(), encoding="utf-8")
+        return target
+
+
+class CompositeRegistry(Registry):
+    """Explicitly ordered registry sources; first source wins on duplicate names."""
+
+    def __init__(self, registries: Iterable[Registry]) -> None:
+        self.registries = tuple(registries)
+
+    def get(self, name: str) -> Skill:
+        """Get a skill from first source containing it."""
+        errors: list[str] = []
+        for registry in self.registries:
+            try:
+                return registry.get(name)
+            except RegistryError as exc:
+                errors.append(str(exc))
+        raise RegistryError(f"Skill not found: {name}. Sources: {'; '.join(errors)}")
+
+    def search(self, query: str) -> list[Skill]:
+        """Search all sources and de-duplicate by name."""
+        found: dict[str, Skill] = {}
+        for registry in self.registries:
+            for skill in registry.search(query):
+                found.setdefault(skill.name, skill)
+        return sorted(found.values(), key=lambda skill: skill.name)
+
+    def install(self, name: str, destination: Path) -> Path:
+        """Install a skill resolved from ordered sources."""
+        skill = self.get(name)
+        destination.mkdir(parents=True, exist_ok=True)
+        target = destination / "SKILL.md"
+        target.write_text(skill.render(), encoding="utf-8")
+        return target

skillforge/skill.py

@@ -0,0 +1,76 @@
+"""The universal SKILL.md document model."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .errors import SkillParseError, SkillValidationError
+
+_SAFE_NAME = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+
+
+@dataclass(frozen=True, slots=True)
+class Skill:
+    """A portable skill with validated YAML metadata and Markdown content."""
+
+    name: str
+    description: str
+    body: str
+
+    def __post_init__(self) -> None:
+        self.validate_name(self.name)
+        if not isinstance(self.description, str) or not self.description.strip():
+            raise SkillValidationError("Skill description is required")
+
+    @staticmethod
+    def validate_name(name: str) -> None:
+        """Validate a skill name before using it as a filesystem path."""
+        if not isinstance(name, str) or not name.strip():
+            raise SkillValidationError("Skill name is required")
+        if not _SAFE_NAME.fullmatch(name):
+            raise SkillValidationError(
+                "Skill name must be safe for filesystem paths: "
+                "lowercase letters, numbers, '-' or '_' only"
+            )
+
+    @classmethod
+    def load(cls, path: Path) -> "Skill":
+        """Load and validate a SKILL.md file from disk."""
+        try:
+            return parse_skill(path.read_text(encoding="utf-8"))
+        except OSError as exc:
+            raise SkillParseError(f"Unable to read skill file {path}: {exc}") from exc
+
+    def render(self) -> str:
+        """Render the skill as a canonical SKILL.md document."""
+        metadata = yaml.safe_dump(
+            {"name": self.name, "description": self.description},
+            sort_keys=False,
+            allow_unicode=False,
+        ).strip()
+        return f"---\n{metadata}\n---\n\n{self.body}"
+
+
+def parse_skill(document: str) -> Skill:
+    """Parse a SKILL.md document with YAML frontmatter."""
+    if not document.startswith("---"):
+        raise SkillParseError("SKILL.md must begin with YAML frontmatter")
+    parts = document.split("---", 2)
+    if len(parts) != 3:
+        raise SkillParseError("SKILL.md frontmatter must be closed with '---'")
+    try:
+        metadata: Any = yaml.safe_load(parts[1])
+    except yaml.YAMLError as exc:
+        raise SkillParseError(f"Invalid YAML frontmatter: {exc}") from exc
+    if not isinstance(metadata, dict):
+        raise SkillValidationError("Skill frontmatter must be a mapping")
+    return Skill(
+        name=metadata.get("name", ""),
+        description=metadata.get("description", ""),
+        body=parts[2].lstrip("\r\n"),
+    )