agent-skillforge 0.1.0__tar.gz

agent_skillforge-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,54 @@
+# 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/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-skillforge"
+version = "0.1.0"
+description = "Portable SKILL.md registry, adapters, CLI, and MCP server."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "gintingism", email = "gintingism@users.noreply.github.com" },
+]
+keywords = ["skills", "mcp", "copilot", "claude", "developer-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=2.3.0",
+    "PyYAML>=6.0",
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.10",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "types-PyYAML>=6.0",
+]
+docs = [
+    "mkdocs-material>=9.5",
+]
+
+[project.scripts]
+skillforge = "skillforge.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/gintingism/skillforge"
+Repository = "https://github.com/gintingism/skillforge"
+Issues = "https://github.com/gintingism/skillforge/issues"
+Documentation = "https://gintingism.github.io/skillforge/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+skillforge = ["builtin_skills/*/SKILL.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.mypy]
+strict = true
+packages = ["skillforge"]
+
+[tool.coverage.report]
+fail_under = 80

agent_skillforge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_skillforge-0.1.0/src/agent_skillforge.egg-info/PKG-INFO

@@ -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/src/agent_skillforge.egg-info/SOURCES.txt

@@ -0,0 +1,30 @@
+LICENSE
+README.md
+pyproject.toml
+src/agent_skillforge.egg-info/PKG-INFO
+src/agent_skillforge.egg-info/SOURCES.txt
+src/agent_skillforge.egg-info/dependency_links.txt
+src/agent_skillforge.egg-info/entry_points.txt
+src/agent_skillforge.egg-info/requires.txt
+src/agent_skillforge.egg-info/top_level.txt
+src/skillforge/__init__.py
+src/skillforge/__main__.py
+src/skillforge/adapters.py
+src/skillforge/cli.py
+src/skillforge/errors.py
+src/skillforge/mcp_server.py
+src/skillforge/registry.py
+src/skillforge/skill.py
+src/skillforge/builtin_skills/agent-observability/SKILL.md
+src/skillforge/builtin_skills/caveman/SKILL.md
+src/skillforge/builtin_skills/human-in-the-loop/SKILL.md
+src/skillforge/builtin_skills/self-improving-agent/SKILL.md
+src/skillforge/builtin_skills/spec-driven-development/SKILL.md
+src/skillforge/builtin_skills/summarize/SKILL.md
+src/skillforge/builtin_skills/tavily-search/SKILL.md
+tests/test_adapters.py
+tests/test_builtins.py
+tests/test_cli.py
+tests/test_mcp_server.py
+tests/test_registry.py
+tests/test_skill.py

agent_skillforge-0.1.0/src/agent_skillforge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_skillforge-0.1.0/src/agent_skillforge.egg-info/entry_points.txt

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

agent_skillforge-0.1.0/src/agent_skillforge.egg-info/requires.txt

@@ -0,0 +1,12 @@
+mcp>=2.3.0
+PyYAML>=6.0
+typer>=0.12
+
+[dev]
+mypy>=1.10
+pytest>=8.0
+pytest-cov>=5.0
+types-PyYAML>=6.0
+
+[docs]
+mkdocs-material>=9.5

agent_skillforge-0.1.0/src/agent_skillforge.egg-info/top_level.txt

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

agent_skillforge-0.1.0/src/skillforge/__init__.py

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

agent_skillforge-0.1.0/src/skillforge/__main__.py

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

agent_skillforge-0.1.0/src/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)]

agent_skillforge-0.1.0/src/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.

agent_skillforge-0.1.0/src/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.

agent_skillforge-0.1.0/src/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.

agent_skillforge-0.1.0/src/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.

agent_skillforge-0.1.0/src/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.

agent_skillforge-0.1.0/src/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.

agent_skillforge-0.1.0/src/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.