{"id":48837162,"url":"https://github.com/gfernandf/agent-skills","last_synced_at":"2026-05-01T00:00:54.592Z","repository":{"id":348091076,"uuid":"1173630767","full_name":"gfernandf/agent-skills","owner":"gfernandf","description":"Agents should execute whenever possible — runtime for composable AI agent skills","archived":false,"fork":false,"pushed_at":"2026-04-27T15:47:47.000Z","size":2373,"stargazers_count":9,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-27T17:25:26.505Z","etag":null,"topics":["agents","ai","capabilities","llm","orca","python","skills","workflows"],"latest_commit_sha":null,"homepage":"https://gfernandf.github.io/agent-skills/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gfernandf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":"docs/GOVERNANCE_TRANSITION.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["gfernandf"]}},"created_at":"2026-03-05T15:24:50.000Z","updated_at":"2026-04-27T15:47:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gfernandf/agent-skills","commit_stats":null,"previous_names":["gfernandf/agent-skills"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/gfernandf/agent-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gfernandf%2Fagent-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gfernandf%2Fagent-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gfernandf%2Fagent-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gfernandf%2Fagent-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gfernandf","download_url":"https://codeload.github.com/gfernandf/agent-skills/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gfernandf%2Fagent-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32480557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"ssl_error","status_checked_at":"2026-04-30T13:12:06.837Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","capabilities","llm","orca","python","skills","workflows"],"created_at":"2026-04-15T00:00:40.746Z","updated_at":"2026-05-01T00:00:54.585Z","avatar_url":"https://github.com/gfernandf.png","language":"Python","funding_links":["https://github.com/sponsors/gfernandf"],"categories":["Frameworks"],"sub_categories":["Tools"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"orca.png\" alt=\"Agent Skills\" width=\"200\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eAgent Skills Runtime\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eAgents should execute whenever possible.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/orca-agent-skills/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/orca-agent-skills.svg\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/gfernandf/agent-skills/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/gfernandf/agent-skills/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Python-3.11%2B-blue.svg\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tests-1694_passed-brightgreen.svg\" alt=\"Tests\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Capabilities-141-blueviolet.svg\" alt=\"Capabilities\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Skills-36-blueviolet.svg\" alt=\"Skills\"\u003e\n  \u003ca href=\"https://doi.org/10.5281/zenodo.19438943\"\u003e\u003cimg src=\"https://zenodo.org/badge/DOI/10.5281/zenodo.19438943.svg\" alt=\"DOI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**A deterministic, binding-driven execution engine for composable AI agent skills.**\n\nAgent Skills Runtime lets you define agent capabilities as abstract contracts, wire them to any backend (Python, OpenAPI, MCP, OpenRPC), and execute multi-step workflows as declarative DAGs — with built-in safety gates, cognitive state tracking, and full observability.\n\n\u003e **No API keys required.** 141 capabilities ship with deterministic Python baselines.\n\u003e Install, run your first skill in under 3 minutes.\n\n---\n\n## ⚡ 30-second start\n\n\u003e Works on macOS, Linux, and Windows. No API key required.\n\n```bash\n# 1 — clone and install\ngit clone https://github.com/gfernandf/agent-skills.git\ncd agent-skills\npip install -e .          # first run takes ~30-60 s — normal\n\n# 2 — get the capability registry (clone it alongside agent-skills/)\ngit clone https://github.com/gfernandf/agent-skill-registry.git ../agent-skill-registry\n\n# 3 — verify everything is wired\npython skills.py doctor\n\n# 4 — run your first skill (no API key needed)\n# macOS / Linux / Git Bash:\nunset OPENAI_API_KEY\npython skills.py run text.language-summary \\\n  --input '{\"text\": \"ORCA decouples agent reasoning from execution. Skills are DAGs, not prompt chains.\"}' \\\n  2\u003e/dev/null\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows PowerShell alternative for step 4\u003c/summary\u003e\n\n```powershell\n$env:OPENAI_API_KEY = \"\"\n'{ \"text\": \"ORCA decouples agent reasoning from execution.\" }' | Set-Content input_qs.json -Encoding ascii\npython skills.py run text.language-summary --input-file input_qs.json 2\u003e$null\nRemove-Item input_qs.json\n```\n\u003c/details\u003e\n\nExpected output:\n```json\n{\"language\": \"en\", \"summary\": \"ORCA decouples agent reasoning from execution...\"}\n```\n\nNo API key. No server. Pure Python baseline, runs offline.\n[→ Full Quick Start](#quick-start) · [→ Use with LangChain / OpenAI / Gemini / MCP](#choosing-your-integration-mode)\n\n---\n\n## 🧩 Mental Model\n\nThink of Agent Skills as:\n\n- **APIs** → turned into reusable “capabilities”  \n- **Workflows (Zapier / Airflow)** → turned into “skills”  \n- **Agent reasoning** → made explicit via structured state  \n\nIn short:\n\n\u003e Agent Skills lets agents execute **structured workflows over tools**, instead of guessing what to do via prompts.\n\n---\n\n## Table of Contents\n\n- [Mental Model](#-mental-model)\n- [Introducing ORCA](#-introducing-orca)\n- [Why Agent Skills?](#why-agent-skills)\n- [When should you use Agent Skills?](#-when-should-you-use-agent-skills)\n- [Architecture](#architecture)\n- [How it compares](#how-it-compares)\n- [Quick Start](#quick-start)\n  - [Install from PyPI](#install-from-pypi)\n  - [Install from source](#install-from-source)\n  - [Run your first skill](#run-your-first-skill)\n  - [Integration modes](#choosing-your-integration-mode)\n- [Advanced Features](#advanced-features)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n- [Citing](#citing)\n\n---\n\n## 🧠 Introducing ORCA\n\n**Agent Skills Runtime is a reference implementation of ORCA — an emerging standard for structured agent execution.**\n\n\u003e ORCA (Open Cognitive Runtime Architecture) defines a **Cognitive Execution Layer** where agents do not act through prompts, but through **composable, contract-driven processes**.\n\nUnlike traditional agent frameworks that rely on implicit reasoning inside LLMs, ORCA externalizes cognition into:\n\n- **Structured state (CognitiveState)** — explicit, inspectable reasoning  \n- **Capabilities (contracts)** — reusable, binding-agnostic operations  \n- **Skills (execution graphs)** — deterministic, composable workflows  \n- **Built-in safety** — enforced execution constraints and validation  \n\nThis shifts agent systems from:\n\n- prompt-driven behavior  \n→ to  \n- **execution-driven systems**\n\n---\n\n### 🔹 Core Principles of ORCA\n\n- **Execution over prompting**  \n- **Explicit state over implicit context**  \n- **Contracts over conventions**  \n- **Separation of intent and execution**  \n- **Safety as a first-class concern**\n\n---\n\n### 🔹 Learn more\n\nSee the full ORCA specification:  \n👉 [`ORCA.md`](ORCA.md)\n\n---\n\n## Why Agent Skills?\n\n| Problem | How Agent Skills solves it |\n|---------|--------------------------|\n| Tools are coupled to one framework | **Binding abstraction** — same capability, 4 protocols (PythonCall, OpenAPI, MCP, OpenRPC) |\n| Workflows are imperative code | **Declarative YAML skills** — steps, dependencies, mappings resolved by the runtime |\n| No safety model | **4-tier safety gates** — trust levels, confirmation prompts, scope constraints, side-effect tracking |\n| No structured reasoning state | **CognitiveState v1** — typed Frame/Working/Output/Trace aligned with CoALA |\n| Inconsistent naming | **Controlled vocabulary** — 122 capabilities across 27 domains with governed naming |\n| Hard to observe | **OTel + metrics + audit** — hash-chain audit trail, Prometheus metrics, SSE streaming |\n\n---\n\n## 🤔 When should you use Agent Skills?\n\nUse it if you need:\n\n- Deterministic and reproducible agent behavior  \n- Safe interaction with real systems (APIs, databases, etc.)  \n- Reusable workflows instead of prompt engineering  \n- Observability and auditability of agent execution  \n\nAvoid it if:\n\n- You just need a quick prompt-based prototype  \n- You don’t need control over execution or safety  \n\n---\n\n## Architecture\n\n\u003e **Note:** The diagram below uses [Mermaid](https://mermaid.js.org/). It renders natively on GitHub. If viewing on PyPI or another platform, see the [architecture diagram on GitHub](https://github.com/gfernandf/agent-skills#architecture).\n\n```mermaid\ngraph TB\n    subgraph \"Developer Interface\"\n        CLI[\"CLI\u003cbr/\u003eagent-skills run / describe / scaffold / test\"]\n        HTTP[\"HTTP API\u003cbr/\u003eREST + SSE streaming\"]\n        SDK[\"SDKs\u003cbr/\u003ePython · TypeScript · LangChain · CrewAI · AutoGen · SemanticKernel\"]\n        MCP_SERVER[\"MCP Server\u003cbr/\u003estdio + SSE transport\"]\n        LLM_NATIVE[\"Native LLM Adapters\u003cbr/\u003eAnthropic · OpenAI · Gemini\"]\n    end\n\n    subgraph \"Gateway Layer\"\n        GW[\"Skill Gateway\u003cbr/\u003eDiscovery · Ranking · Governance\"]\n    end\n\n    subgraph \"Execution Engine\"\n        SCHED[\"DAG Scheduler\u003cbr/\u003eKahn's topological sort · parallel / sequential\"]\n        POLICY[\"Policy Engine\u003cbr/\u003eSafety gates · Trust levels · Confirmation\"]\n        COGSTATE[\"CognitiveState v1\u003cbr/\u003eFrame · Working · Output · Trace\"]\n    end\n\n    subgraph \"Binding Layer\"\n        BR[\"Binding Resolver\u003cbr/\u003eProtocol routing · Fallback chain · Conformance\"]\n        PC[\"PythonCall\"]\n        OA[\"OpenAPI\"]\n        MCP_P[\"MCP\"]\n        RPC[\"OpenRPC\"]\n    end\n\n    subgraph \"Services\"\n        BASELINE[\"Python Baselines\u003cbr/\u003e122 deterministic functions\"]\n        EXTERNAL[\"External APIs\u003cbr/\u003eOpenAI · custom services\"]\n        MCP_SRV[\"MCP Servers\u003cbr/\u003eIn-process + subprocess\"]\n    end\n\n    CLI --\u003e GW\n    HTTP --\u003e GW\n    SDK --\u003e HTTP\n    MCP_SERVER --\u003e GW\n    LLM_NATIVE --\u003e GW\n    GW --\u003e SCHED\n    SCHED --\u003e POLICY\n    POLICY --\u003e BR\n    SCHED -.-\u003e COGSTATE\n    BR --\u003e PC --\u003e BASELINE\n    BR --\u003e OA --\u003e EXTERNAL\n    BR --\u003e MCP_P --\u003e MCP_SRV\n    BR --\u003e RPC --\u003e EXTERNAL\n```\n\n---\n\n## How it compares\n\n| Dimension | Agent Skills | LangGraph | SemanticKernel | OpenAI SDK | CrewAI |\n|-----------|:-----:|:-----:|:-----:|:-----:|:-----:|\n| **DAG Execution** | ✅ Kahn sort | ✅ StateGraph | ⚠️ Linear | ⚠️ Tool-loop | ⚠️ Sequential |\n| **Multi-Protocol Bindings** | ✅ 4 protocols | ❌ Python only | ⚠️ HTTP+plugins | ❌ Function only | ❌ Function only |\n| **Safety Model** | ✅ 4-tier gates | ❌ None | ⚠️ Basic | ❌ Minimal | ❌ None |\n| **Cognitive State** | ✅ Typed (CoALA) | ❌ No formal | ❌ No formal | ❌ No formal | ⚠️ Roles |\n| **Capability Registry** | ✅ 122 governed | ❌ None | ⚠️ Plugin store | ❌ None | ⚠️ Templates |\n| **Observability** | ✅ OTel+Metrics+Audit | ✅ LangSmith | ⚠️ AppInsights | ⚠️ Log-only | ⚠️ Basic |\n| **Zero-config local run** | ✅ Python baselines | ⚠️ Needs LLM key | ⚠️ Needs Azure | ❌ Needs API key | ⚠️ Needs LLM key |\n| **Declarative workflows** | ✅ YAML skills | ⚠️ Python code | ⚠️ C# code | ❌ Imperative | ⚠️ Python code |\n| **Checkpoint/Restore** | ✅ Full state | ✅ Checkpoints | ✅ State | ❌ Stateless | ⚠️ Memory |\n\n---\n\n## Quick Start\n\n### Install from PyPI\n\n```bash\npip install orca-agent-skills          # core\npip install orca-agent-skills[all]     # + PDF, web, OTel extras\npip install orca-agent-skills[mcp]     # + MCP server/client\npip install orca-agent-skills[dev]     # + pytest, ruff, benchmarks\n```\n\nThe PyPI package includes the execution engine and CLI. You'll also need the companion **[agent-skill-registry](https://github.com/gfernandf/agent-skill-registry)** (capability contracts, skills, vocabulary):\n\n```bash\ngit clone https://github.com/gfernandf/agent-skill-registry.git\npython skills.py doctor   # verifies registry is found\n```\n\n\u003e **Windows note:** After `pip install`, if `agent-skills` is not found in your shell, run the following once to add Python's `Scripts/` to your PATH — then restart your terminal:\n\u003e ```powershell\n\u003e [System.Environment]::SetEnvironmentVariable(\"PATH\", $env:PATH + \";\" + (python -c \"import sysconfig; print(sysconfig.get_path('scripts'))\"), \"User\")\n\u003e ```\n\u003e Or use `python skills.py` from the repo root as a drop-in replacement for all `agent-skills` commands throughout this README.\n\n### Install from source\n\n**macOS / Linux:**\n```bash\ngit clone https://github.com/gfernandf/agent-skills.git\ncd agent-skills\nmake bootstrap       # clones registry alongside, installs deps\npython skills.py doctor\n```\n\n**Windows (PowerShell):**\n```powershell\ngit clone https://github.com/gfernandf/agent-skills.git\ncd agent-skills\npip install -e \".[all,dev]\"\ngit clone https://github.com/gfernandf/agent-skill-registry.git ../agent-skill-registry\npython skills.py doctor\n```\n\n\u003e **What `make bootstrap` does:** clones the registry into `../agent-skill-registry/`, then runs `pip install -e \".[all,dev]\"`. If you prefer manual setup, see [docs/INSTALLATION.md](docs/INSTALLATION.md).\n\n### Run your first skill\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/demo.gif\" alt=\"Agent Skills CLI demo — doctor + summarize\" width=\"800\"\u003e\n\u003c/p\u003e\n\n```bash\n# macOS / Linux / Git Bash (stderr suppressed for clean output):\nunset OPENAI_API_KEY\npython skills.py run text.language-summary \\\n  --input '{\"text\": \"Agent Skills Runtime is a deterministic execution engine for composable AI agent skills. It supports four binding protocols and ships with 141 Python baselines.\"}' \\\n  2\u003e/dev/null\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eWindows PowerShell\u003c/summary\u003e\n\n```powershell\n$env:OPENAI_API_KEY = \"\"\n'{ \"text\": \"Agent Skills Runtime is a deterministic execution engine.\" }' | Set-Content input_run.json -Encoding ascii\npython skills.py run text.language-summary --input-file input_run.json 2\u003e$null\nRemove-Item input_run.json\n```\n\n\u003e **No output or blank screen?** Drop `2\u003e$null` to see the full error message:\n\u003e ```powershell\n\u003e python skills.py run text.language-summary --input-file input_run.json\n\u003e ```\n\u003c/details\u003e\n\nExpected output:\n```json\n{\n  \"language\": \"en\",\n  \"summary\": \"Agent Skills Runtime is a deterministic execution engine...\"\n}\n```\n\n\u003e **Tip:** Trace/telemetry events are written to stderr. Redirect with `2\u003e/dev/null` (bash) or `2\u003e$null` (PowerShell) for clean output. Use `--audit-mode off` to disable audit records entirely.\n\n### Run via HTTP\n\n```bash\nagent-skills serve                     # starts server on :8080\ncurl http://localhost:8080/v1/health   # health check\ncurl -X POST http://localhost:8080/v1/skills/text.language-summary/execute \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"inputs\": {\"text\": \"Hello world from ORCA\"}}'\n```\n\n### Baseline → LLM: same skill, two modes\n\nEvery capability ships with a deterministic Python baseline. Set `OPENAI_API_KEY` to upgrade to LLM-powered execution — **zero code changes**.\n\n```bash\n# 1. Baseline mode (no API key, pure Python)\npython skills.py run text.language-summary \\\n  --input '{\"text\": \"Agent Skills decouples capability contracts from execution backends.\"}' \\\n  2\u003e/dev/null\n# → {\"language\": \"en\", \"summary\": \"Agent Skills decouples capability contracts from execution backends.\"}\n\n# 2. LLM mode (set key, same command — zero code changes)\nexport OPENAI_API_KEY=sk-...          # bash\n# $env:OPENAI_API_KEY = \"sk-...\"      # PowerShell\npython skills.py run text.language-summary \\\n  --input '{\"text\": \"Agent Skills decouples capability contracts from execution backends.\"}' \\\n  2\u003e/dev/null\n# → {\"language\": \"en\", \"summary\": \"Agent Skills separates capability definitions from their runtime implementations.\"}\n```\n\nThe binding resolver picks the best available backend automatically:\n- **No key** → `PythonCall` baseline (deterministic, offline, fast)\n- **Key set** → `OpenAPI` binding to OpenAI (richer output, higher latency)\n\nThis means your CI stays green without API keys, and production gets LLM quality — from the same skill YAML.\n\nSee [docs/INSTALLATION.md](docs/INSTALLATION.md) for full setup instructions, optional extras, and environment variable reference.\n\n### Use with LangChain / LangGraph\n\n```python\nfrom sdk.embedded import as_langchain_tools\n\n# No server needed — runs in-process\ntools = as_langchain_tools([\"text.content.summarize\", \"text.content.translate\"])\n# Pass tools to any LangChain AgentExecutor or LangGraph node\nagent = create_react_agent(llm, tools)\n```\n\nAdapters are also available for **CrewAI**, **AutoGen**, and **Semantic Kernel** — see the [sdk/](sdk/) directory.\n\n### Use as MCP Server\n\nExpose all 122 capabilities as MCP tools over stdio (or SSE) — any MCP-compatible host (Claude Desktop, VS Code Copilot, etc.) can discover and call them:\n\n```bash\n# stdio transport (default — for Claude Desktop / MCP hosts)\npython -m official_mcp_servers\n\n# SSE transport (for network clients)\npython -m official_mcp_servers --sse --host 0.0.0.0 --port 8765\n\n# Or via the CLI\nagent-skills mcp-serve\nagent-skills mcp-serve --sse --port 8765\n```\n\nRequires the `mcp` extra: `pip install -e \".[mcp]\"`\n\n### Native LLM Tool Definitions\n\nGenerate provider-native tool arrays for Anthropic, OpenAI, and Gemini — no HTTP server, no adapters, just the format each SDK expects:\n\n```python\nfrom sdk.embedded import (\n    as_anthropic_tools, execute_anthropic_tool_call,\n    as_openai_tools,    execute_openai_tool_call,\n    as_gemini_tools,    execute_gemini_tool_call,\n)\n\n# ── Anthropic ──────────────────────────────────\ntools = as_anthropic_tools([\"text.content.summarize\"])\nresponse = client.messages.create(model=\"claude-sonnet-4-20250514\", tools=tools, ...)\nresult = execute_anthropic_tool_call(block.name, block.input)\n\n# ── OpenAI ─────────────────────────────────────\ntools = as_openai_tools()  # all 122 capabilities\nresponse = openai.chat.completions.create(model=\"gpt-4o\", tools=tools, ...)\nresult = execute_openai_tool_call(call.function.name, call.function.arguments)\n\n# ── Gemini ─────────────────────────────────────\ntools = as_gemini_tools([\"data.schema.validate\"])\nresponse = model.generate_content(contents, tools=tools)\nresult = execute_gemini_tool_call(fc.name, fc.args)\n```\n\nEach `execute_*` helper maps the underscore tool name back to the dotted capability ID and returns a JSON string.\n\n### Choosing your integration mode\n\n| Mode | Best for | Latency | Requires server? |\n|------|----------|---------|:----------------:|\n| **Embedded SDK** (`sdk.embedded`) | Python apps, notebooks, scripts | Lowest (in-process) | No |\n| **Native LLM tools** (`as_anthropic_tools`, etc.) | Direct Anthropic/OpenAI/Gemini integration | Low (in-process) | No |\n| **LangChain / CrewAI / AutoGen** (`as_langchain_tools`, etc.) | Framework-based agents | Low (in-process) | No |\n| **MCP Server** (`python -m official_mcp_servers`) | Claude Desktop, VS Code Copilot, MCP hosts | Low (stdio/SSE) | MCP host |\n| **HTTP REST** (`agent-skills serve`) | Microservices, non-Python clients, multi-tenant | Medium (network) | Yes |\n\n**Start here:** If you're writing Python, use the embedded SDK — zero setup, lowest latency. Switch to HTTP only when you need network access or non-Python clients.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n\n## 📄 Research Paper\n\n\u003e **Beyond Prompting: Decoupling Cognition from Execution in LLM-based Agents through the ORCA Framework**\n\u003e\n\u003e Fernandez Alvarez, G. E. (2026) · [DOI: 10.5281/zenodo.19438943](https://doi.org/10.5281/zenodo.19438943) · [SSRN](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6600840)\n\nThe theoretical foundations of ORCA and this runtime are described in our research paper.\nSee the full [paper landing page](docs/PAPER.md) for abstract, downloads, and citation formats.\n\n📥 [Download PDF](docs/papers/orca_paper_final_clean_v2.pdf) · 📄 [SSRN Entry](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6600840) · 📖 [ORCA Specification](ORCA.md)\n\n---\n\n## Citing\n\nIf you use Agent Skills or ORCA in your research, please cite the paper:\n\n```bibtex\n@article{fernandez_orca_2026,\n  author    = {Fernandez Alvarez, Guillermo E.},\n  title     = {Beyond Prompting: Decoupling Cognition from Execution in\n               LLM-based Agents through the ORCA Framework},\n  year      = {2026},\n  publisher = {Zenodo},\n  doi       = {10.5281/zenodo.19438943},\n  url       = {https://doi.org/10.5281/zenodo.19438943}\n}\n```\n\nTo cite the software specifically:\n\n```bibtex\n@software{fernandez_agent_skills_2026,\n  author       = {Fernandez Alvarez, Guillermo},\n  title        = {Agent Skills Runtime},\n  year         = {2026},\n  url          = {https://github.com/gfernandf/agent-skills},\n  version      = {1.0.0},\n  license      = {Apache-2.0}\n}\n```\n\nGitHub also provides a \"Cite this repository\" button powered by [`CITATION.cff`](CITATION.cff).\n\n---\n\n## Advanced Features\n\n| Feature | Description | Docs |\n|---------|-------------|------|\n| **NL Autopilot** | `agent-skills ask \"summarize this\"` — discovers, maps, executes | [SKILL_AUTHORING.md](docs/SKILL_AUTHORING.md) |\n| **Dev Watch** | Hot-reload skill development with `agent-skills dev` | [SKILL_AUTHORING.md](docs/SKILL_AUTHORING.md) |\n| **Skill Triggers** | Declarative webhook / event / file-change triggers | [WEBHOOKS.md](docs/WEBHOOKS.md) |\n| **Benchmark Lab** | Compare binding protocols side-by-side | CLI: `agent-skills benchmark-lab` |\n| **Compose DSL** | Compact `.compose` text syntax for workflows | CLI: `agent-skills compose` |\n| **Showcase** | One-command shareable markdown for any skill | CLI: `agent-skills showcase` |\n| **Local Capabilities** | Custom capabilities via `.agent-skills/capabilities/` with `extends` | [SKILL_AUTHORING.md](docs/SKILL_AUTHORING.md) |\n| **Auth \u0026 RBAC** | 4 hierarchical roles, API key + JWT, pluggable | [AUTH.md](docs/AUTH.md) |\n| **Webhooks** | HMAC-signed event payloads with auto-retry | [WEBHOOKS.md](docs/WEBHOOKS.md) |\n| **Plugin System** | Entry-point based auth, invoker, and binding-source plugins | [PLUGINS.md](docs/PLUGINS.md) |\n| **Audit Trail** | Hash-chain audit with `off`/`standard`/`full` modes | [OBSERVABILITY.md](docs/OBSERVABILITY.md) |\n| **CognitiveState v1** | Typed Frame/Working/Output/Trace aligned with CoALA | [COGNITIVE_STATE_V1.md](docs/COGNITIVE_STATE_V1.md) |\n| **JSON Schemas** | 16 schemas (2020-12) for capabilities, skills, bindings | [JSON_SCHEMAS.md](docs/JSON_SCHEMAS.md) |\n| **Governance Catalog** | Skill lifecycle: draft → validated → trusted → recommended | [SKILL_GOVERNANCE_MANIFESTO.md](docs/SKILL_GOVERNANCE_MANIFESTO.md) |\n| **Binding Conformance** | `strict`/`standard`/`experimental` profiles per binding | [CONSUMER_FACING_NEUTRAL_API.md](docs/CONSUMER_FACING_NEUTRAL_API.md) |\n| **Binding Fallback** | Deterministic fallback chain with terminal baseline | [RUNNER_GUIDE.md](docs/RUNNER_GUIDE.md) |\n\n## Skill Authoring\n\n```bash\n# LLM-powered wizard — generates a complete skill from a plain-language goal\n# Requires OPENAI_API_KEY (see .env.example)\nexport OPENAI_API_KEY=sk-...\nagent-skills scaffold --wizard               # LLM proposes workflow + YAML\nagent-skills scaffold \"Summarize a PDF\"      # one-line from intent\nagent-skills scaffold --wizard --dry-run     # preview without saving\n\n# Without OPENAI_API_KEY, the wizard falls back to manual interactive mode\n# (you pick inputs, outputs, and capabilities yourself)\n\nagent-skills test text.summarize              # auto-fixture tests\nagent-skills describe text.summarize --mermaid  # DAG diagram\nagent-skills export text.summarize            # portable bundle\nagent-skills contribute text.summarize        # promotion pipeline\n```\n\nSee [docs/SKILL_AUTHORING.md](docs/SKILL_AUTHORING.md) for the full workflow guide.\n\n## Documentation\n\n| Topic | Link |\n|-------|------|\n| 10-minute onboarding | [ONBOARDING_10_MIN.md](docs/ONBOARDING_10_MIN.md) |\n| Installation \u0026 setup | [INSTALLATION.md](docs/INSTALLATION.md) |\n| Environment variables | [ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) |\n| Error taxonomy | [ERROR_TAXONOMY.md](docs/ERROR_TAXONOMY.md) |\n| Runner architecture | [RUNNER_GUIDE.md](docs/RUNNER_GUIDE.md) |\n| DAG scheduler | [SCHEDULER.md](docs/SCHEDULER.md) |\n| Step control flow | [STEP_CONTROL_FLOW.md](docs/STEP_CONTROL_FLOW.md) |\n| Streaming SSE | [STREAMING.md](docs/STREAMING.md) |\n| Async execution | [ASYNC_EXECUTION.md](docs/ASYNC_EXECUTION.md) |\n| Deployment \u0026 Docker | [DEPLOYMENT.md](docs/DEPLOYMENT.md) |\n| Observability \u0026 OTel | [OBSERVABILITY.md](docs/OBSERVABILITY.md) |\n| Authentication \u0026 RBAC | [AUTH.md](docs/AUTH.md) |\n| Security | [SECURITY.md](SECURITY.md) |\n| OpenAPI foundation | [OPENAPI_PHASE0_FOUNDATION.md](docs/OPENAPI_PHASE0_FOUNDATION.md) |\n| MCP integration | [MCP_INTEGRATION_SLICES.md](docs/MCP_INTEGRATION_SLICES.md) |\n| Governance manifesto | [SKILL_GOVERNANCE_MANIFESTO.md](docs/SKILL_GOVERNANCE_MANIFESTO.md) |\n| Project status | [PROJECT_STATUS.md](docs/PROJECT_STATUS.md) |\n\nFull documentation is served with MkDocs: `make serve` → http://localhost:8000\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n```bash\nmake check   # lint + format + tests in one command\n```\n\nLooking for a good first issue? Check the [help wanted](https://github.com/gfernandf/agent-skills/issues?q=is%3Aopen+label%3A%22help+wanted%22) list.\n\n\u003e ⭐ If Agent Skills saves you time or you find the ideas useful, a star helps others discover the project.\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| `RegistryNotFound` | Run `agent-skills doctor --fix` to auto-clone the registry |\n| Skill returns unexpected error | See [Error Taxonomy](docs/ERROR_TAXONOMY.md) for frozen error codes |\n| Environment config issues | Check [Environment Variables](docs/ENVIRONMENT_VARIABLES.md) |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgfernandf%2Fagent-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgfernandf%2Fagent-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgfernandf%2Fagent-skills/lists"}