Skip to content
Back to search

agent-skills

Not another agent orchestrator — ORCA is a runtime for executable cognition.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gfernandf--agent-skills/badge.svg)](/listings/gfernandf--agent-skills)

HTML

<a href="/listings/gfernandf--agent-skills"><img src="/api/listings/gfernandf--agent-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 525 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="orca.png" alt="Agent Skills" width="200">
  3. </p>
  4. <h1 align="center">Agent Skills Runtime</h1>
  5. <p align="center">
  6. <em>Agents should execute whenever possible.</em>
  7. </p>
  8. <p align="center">
  9. <a href="https://pypi.org/project/orca-agent-skills/"><img src="https://img.shields.io/pypi/v/orca-agent-skills.svg" alt="PyPI"></a>
  10. <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
  11. <a href="https://github.com/gfernandf/agent-skills/actions/workflows/ci.yml"><img src="https://github.com/gfernandf/agent-skills/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  12. <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11%2B-blue.svg" alt="Python"></a>
  13. <img src="https://img.shields.io/badge/Capabilities-184-blueviolet.svg" alt="Capabilities">
  14. <img src="https://img.shields.io/badge/Skills-39-blueviolet.svg" alt="Skills">
  15. <a href="https://doi.org/10.5281/zenodo.19438943"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19438943.svg" alt="DOI"></a>
  16. </p>
  17. Agent Skills turns repeatable agent reasoning into executable skills: reusable, testable, observable, and portable across tools and model providers.
  18. Stop rebuilding agent logic in prompts. Define it once as a skill, bind it to any backend, and run it with full traceability.
  19. Agent Skills Runtime is the reference implementation of ORCA (Open Cognitive Runtime Architecture):
  20. - Skills package reusable cognitive workflows
  21. - Capabilities define backend-agnostic contracts
  22. - Bindings connect contracts to execution backends (PythonCall, OpenAPI, MCP, OpenRPC)
  23. - Runtime executes DAGs with policy/safety, CognitiveState, and traceability
  24. ## Terminology Note
  25. For cognitive runtime terminology, we use:
  26. - COGIT = capability
  27. - SYLLOG = skill
  28. In this repository implementation, we keep the canonical technical terms
  29. `capability/capabilities` and `skill/skills` (file paths, APIs, schemas, CLI,
  30. catalogs, and runtime internals) to preserve architecture and compatibility.
  31. No API key required for local-first runs. Deterministic Python baselines are available for offline development and testing.
  32. ---
  33. ## The problem
  34. Most agent systems still encode critical logic inside prompts and framework glue.
  35. That creates recurring engineering pain:
  36. - Reasoning logic gets trapped in prompt text instead of executable workflows
  37. - Workflows are hard to reuse and harder to test
  38. - Contracts between steps are implicit and brittle
  39. - Observability and auditability are often an afterthought
  40. - Safety and governance controls are inconsistent
  41. - Switching providers or frameworks usually means rewriting too much
  42. ---
  43. ## The ORCA answer
  44. ORCA introduces an execution layer for cognitive workflows:
  45. - Skills are reusable cognitive workflows
  46. - Capabilities are stable, contract-driven interfaces
  47. - Bindings are interchangeable execution backends
  48. - Runtime is a DAG scheduler + policy engine + cognitive state + trace
  49. This keeps reasoning structure explicit and executable, while preserving portability across backends.
  50. ---
  51. ## Before / after
  52. Before (logic trapped in prompt text):
  53. ```python
  54. prompt = """
  55. Analyze this PR.
  56. Find risks.
  57. Estimate confidence.
  58. Suggest fixes.
  59. Return JSON.
  60. """
  61. ```
  62. After (logic as a reusable skill graph):
  63. ```yaml
  64. # Conceptual example (illustrative structure)
  65. skill: code.pr.review
  66. steps:
  67. - parse_diff
  68. - detect_risks
  69. - score_confidence
  70. - generate_review
  71. - validate_output
  72. ```
  73. Same reasoning pattern. Reusable. Testable. Observable. Bindable to Python, OpenAPI, MCP, or your own APIs.
  74. ---
  75. ## Try it locally in 3 minutes
  76. ```bash
  77. git clone https://github.com/gfernandf/agent-skills.git
  78. cd agent-skills
  79. make bootstrap
  80. python skills.py doctor
  81. python skills.py run text.language-summary \
  82. --input '{"text": "ORCA turns agent reasoning into reusable executable skills."}'
  83. ```
  84. What to expect:
  85. - No API key required
  86. - Runs offline with deterministic Python baselines
  87. - First run may take 30-60 seconds
  88. <details>
  89. <summary>Windows PowerShell setup and run</summary>
  90. ```powershell
  91. git clone https://github.com/gfernandf/agent-skills.git
  92. cd agent-skills
  93. pip install -e ".[all,dev]"
  94. git clone https://github.com/gfernandf/agent-skill-registry.git ../agent-skill-registry
  95. python skills.py doctor
  96. $env:OPENAI_API_KEY = ""
  97. '{ "text": "ORCA turns agent reasoning into reusable executable skills." }' | Set-Content input_qs.json -Encoding ascii
  98. python skills.py run text.language-summary --input-file input_qs.json
  99. Remove-Item input_qs.json
  100. ```
  101. </details>
  102. ---
  103. ## Why this matters beyond a toy summary
  104. The first command verifies install. The stronger demo is the official skill decision.make.
  105. decision.make shows a full decision workflow under uncertainty with explicit stages and auditable outputs.
  106. From the skill contract in the registry, it includes:
  107. - Multi-step pipeline (option generation, analysis, scoring, justification, validation)
  108. - Structured outputs such as recommendation, tradeoffs, confidence_score, confidence_level, uncertainties, and next_steps
  109. - Risk-aware reasoning through explicit criteria and constraints
  110. - Trace-friendly execution aligned with ORCA observability goals
  111. Conceptual output shape for decision-style workflows:
  112. ```json
  113. {
  114. "recommendation": "Proceed with a controlled pilot",
  115. "confidence_score": 0.82,
  116. "confidence_level": "medium",
  117. "tradeoffs": [
  118. "Faster learning, higher short-term operational overhead"
  119. ],
  120. "uncertainties": [
  121. "Regulatory timeline may change in Q3"
  122. ],
  123. "next_steps": [
  124. "Run a 6-week pilot in one segment"
  125. ],
  126. "trace_id": "..."
  127. }
  128. ```
  129. Note: the JSON above is illustrative. Exact outputs depend on input context, bindings, and policy settings.
  130. ---
  131. ## I want to...
  132. ### I want to try it
  133. - Start with local CLI: see Try it locally in 3 minutes
  134. - Use deterministic baselines for offline reproducibility
  135. - Explore first workflows in examples and docs
  136. ### I want to integrate it
  137. Choose one integration surface:
  138. - Embedded SDK (lowest latency, in-process)
  139. - HTTP API (service boundary, non-Python clients)
  140. - MCP server (tooling ecosystems and MCP hosts)
  141. - Framework adapters (LangChain, CrewAI, AutoGen, Semantic Kernel)
  142. - Native tool definitions (Anthropic, OpenAI, Gemini)
  143. ### I want to build skills
  144. - Author declarative skills as DAG workflows
  145. - Reuse existing capability contracts
  146. - Validate wiring and execution behavior
  147. - Package and contribute reusable workflows
  148. ---
  149. ## Mental model
  150. Think of Agent Skills as:
  151. - Capabilities: what an operation means (contract)
  152. - Bindings: how that operation is executed (backend)
  153. - Skills: how operations compose into workflows (DAG)
  154. - Runtime: how workflows execute safely and observably
  155. ## Cognitive Taxonomy
  156. The pure cognitive layer is intentionally narrower than the full runtime.
  157. The current taxonomy separates:
  158. - **Pure cognitive capabilities**: decision, evaluation, evidence, memory,
  159. perception, and reasoning.
  160. - **Compatibility surfaces**: legacy or transitional names such as `eval.*`
  161. that remain in the live registry during migration.
  162. - **Operational capabilities**: routing, delegation, workflow control, and
  163. other runtime helpers that should not be counted as core cognition.
  164. The registry-level reference for that taxonomy is:
  165. - [agent-skill-registry/docs/COGNITIVE_TAXONOMY.md](../agent-skill-registry/docs/COGNITIVE_TAXONOMY.md)
  166. Use that document as the source of truth when deciding whether a capability
  167. belongs to the cognitive core or to the operational layer.
  168. ---
  169. ## Core concepts
  170. ### Skills
  171. Reusable cognitive workflows declared as DAGs.
  172. ### Capabilities
  173. Backend-agnostic contracts with typed inputs and outputs.
  174. ### Bindings
  175. Execution adapters for PythonCall, OpenAPI, MCP, and OpenRPC.
  176. ### Runtime
  177. Execution layer with DAG scheduling, policy gates, cognitive state, and trace.
  178. ---
  179. ## Integration modes
  180. | Mode | Best for | Requires server? |
  181. |------|----------|:----------------:|
  182. | Embedded SDK | Python apps and notebooks | No |
  183. | Native tool defs | Direct model SDK integration | No |
  184. | Framework adapters | Existing agent frameworks | No |
  185. | MCP server | MCP-compatible hosts | MCP host |
  186. | HTTP API | Service-oriented architectures | Yes |
  187. ### Embedded SDK (example)
  188. ```python
  189. from sdk.embedded import as_langchain_tools
  190. tools = as_langchain_tools(["text.content.summarize", "text.content.translate"])
  191. ```
  192. ### HTTP API (example)
  193. ```bash
  194. agent-skills serve
  195. curl http://localhost:8080/v1/health
  196. curl -X POST http://localhost:8080/v1/skills/text.language-summary/execute \
  197. -H "Content-Type: application/json" \
  198. -d '{"inputs": {"text": "Hello world from ORCA"}}'
  199. ```
  200. ### MCP server (example)
  201. ```bash
  202. python -m official_mcp_servers
  203. python -m official_mcp_servers --sse --host 0.0.0.0 --port 8765
  204. ```
  205. ### Native tool definitions (example)
  206. ```python
  207. from sdk.embedded import as_openai_tools, execute_openai_tool_call
  208. tools = as_openai_tools()
  209. # pass tools to your OpenAI client, then dispatch tool calls via execute_openai_tool_call
  210. ```
  211. ---
  212. ## Architecture
  213. ```mermaid
  214. graph TB
  215. subgraph Interface
  216. CLI[CLI]
  217. HTTP[HTTP API]
  218. SDK[Embedded SDK / Adapters]
  219. MCP[MCP Server]
  220. end
  221. subgraph Runtime
  222. GW[Gateway]
  223. SCH[DAG Scheduler]
  224. POL[Policy and Safety]
  225. COG[CognitiveState]
  226. TRC[Trace and Audit]
  227. end
  228. subgraph BindingLayer
  229. RES[Binding Resolver]
  230. PY[PythonCall]
  231. OA[OpenAPI]
  232. MP[MCP]
  233. RP[OpenRPC]
  234. end
  235. subgraph Backends
  236. BASE[Deterministic Python baselines]
  237. EXT[External APIs and services]
  238. MCPB[MCP backends]
  239. end
  240. CLI --> GW
  241. HTTP --> GW
  242. SDK --> GW
  243. MCP --> GW
  244. GW --> SCH
  245. SCH --> POL
  246. SCH --> COG
  247. SCH --> TRC
  248. POL --> RES
  249. RES --> PY --> BASE
  250. RES --> OA --> EXT
  251. RES --> MP --> MCPB
  252. RES --> RP --> EXT
  253. ```
  254. ---
  255. ## How it compares
  256. Agent Skills is not a replacement for every agent framework.
  257. It can run standalone, but its strongest use case is as a reusable execution layer underneath frameworks, tools, and model providers.
  258. | Dimension | Agent Skills | Typical agent framework |
  259. |-----------|--------------|-------------------------|
  260. | Execution model | Declarative DAG skills | Often prompt/tool loop centered |
  261. | Contracts | Capability-first, typed | Usually app-level conventions |
  262. | Backend portability | Binding abstraction layer | Often provider/framework specific |
  263. | Safety/governance | Policy gates and execution controls | Varies widely |
  264. | Observability | Trace and audit oriented | Varies widely |
  265. | Local deterministic mode | Yes, baseline-first workflow | Often key-dependent |
  266. ---
  267. ## Advanced features
  268. - Auth and RBAC controls
  269. - Webhook eventing
  270. - Plugin extension points
  271. - Audit modes and runtime observability
  272. - CognitiveState v1 and cognitive hints
  273. - Runtime-managed output envelope (`status`, `rationale`, `trace_ref`)
  274. - JSON Schema generation and validation
  275. - Skill governance and conformance tooling
  276. ---
  277. ## Cognitive quality gates (>9)
  278. The runtime includes a quality gate bundle for pure cognitive capabilities.
  279. Run the gate pack:
  280. ```bash
  281. python tooling/run_cognitive_quality_gates.py \
  282. --report-file artifacts/cognitive_quality_gates_local_report.json
  283. ```
  284. Generate scorecard only:
  285. ```bash
  286. python tooling/generate_cognitive_quality_scorecard.py \
  287. --fail-on-threshold \
  288. --min-axis 9.0 \
  289. --min-overall 9.0
  290. ```
  291. Primary artifacts:
  292. - `artifacts/cognitive_e2e_contract_report.json`
  293. - `artifacts/cognitive_semantic_all_report.json`
  294. - `artifacts/cognitive_quality_scorecard.json`
  295. - `artifacts/cognitive_quality_gates_local_report.json`
  296. See docs index below for details.
  297. ---
  298. ## Documentation
  299. | Topic | Link |
  300. |-------|------|
  301. | 10-minute onboarding | [docs/ONBOARDING_10_MIN.md](docs/ONBOARDING_10_MIN.md) |
  302. | Target architecture (canonical) | [docs/TARGET_ARCHITECTURE.md](docs/TARGET_ARCHITECTURE.md) |
  303. | Installation | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
  304. | Environment variables | [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) |
  305. | Error taxonomy | [docs/ERROR_TAXONOMY.md](docs/ERROR_TAXONOMY.md) |
  306. | Runner architecture | [docs/RUNNER_GUIDE.md](docs/RUNNER_GUIDE.md) |
  307. | Binding selection policy | [docs/BINDING_SELECTION.md](docs/BINDING_SELECTION.md) |
  308. | Binding authoring guide | [docs/BINDING_GUIDE.md](docs/BINDING_GUIDE.md) |
  309. | DAG scheduler | [docs/SCHEDULER.md](docs/SCHEDULER.md) |
  310. | Step control flow | [docs/STEP_CONTROL_FLOW.md](docs/STEP_CONTROL_FLOW.md) |
  311. | Streaming | [docs/STREAMING.md](docs/STREAMING.md) |
  312. | Async execution | [docs/ASYNC_EXECUTION.md](docs/ASYNC_EXECUTION.md) |
  313. | Deployment | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) |
  314. | Observability | [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md) |
  315. | Auth and RBAC | [docs/AUTH.md](docs/AUTH.md) |
  316. | Webhooks | [docs/WEBHOOKS.md](docs/WEBHOOKS.md) |
  317. | Plugins | [docs/PLUGINS.md](docs/PLUGINS.md) |
  318. | JSON schemas | [docs/JSON_SCHEMAS.md](docs/JSON_SCHEMAS.md) |
  319. | Skill authoring | [docs/SKILL_AUTHORING.md](docs/SKILL_AUTHORING.md) |
  320. | Troubleshooting | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) |
  321. | Public release use cases | [docs/PUBLIC_RELEASE_USE_CASES.md](docs/PUBLIC_RELEASE_USE_CASES.md) |
  322. | Action Preflight integration quickstart | [docs/ACTION_PREFLIGHT_FORECAST_QUICKSTART.md](docs/ACTION_PREFLIGHT_FORECAST_QUICKSTART.md) |
  323. | Action Preflight external freeze/repro | [docs/ACTION_PREFLIGHT_FORECAST_EXTERNAL.md](docs/ACTION_PREFLIGHT_FORECAST_EXTERNAL.md) |
  324. | Action Preflight release note | [docs/ACTION_PREFLIGHT_FORECAST_RELEASE_NOTE.md](docs/ACTION_PREFLIGHT_FORECAST_RELEASE_NOTE.md) |
  325. | Action Preflight external checklist | [docs/ACTION_PREFLIGHT_FORECAST_EXTERNAL_CHECKLIST.md](docs/ACTION_PREFLIGHT_FORECAST_EXTERNAL_CHECKLIST.md) |
  326. | Project status | [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) |
  327. | ORCA specification | [ORCA.md](ORCA.md) |
  328. Serve docs locally:
  329. ```bash
  330. make serve
  331. ```
  332. ---
  333. ## Research paper
  334. Beyond Prompting: Decoupling Cognition from Execution in LLM-based Agents through the ORCA Framework
  335. Fernandez Alvarez, G. E. (2026)
  336. - DOI: https://doi.org/10.5281/zenodo.19438943
  337. - SSRN: https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6600840
  338. - Paper page: [docs/PAPER.md](docs/PAPER.md)
  339. ---
  340. ## Contributing
  341. Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
  342. ```bash
  343. make check
  344. ```
  345. ---
  346. ## License
  347. Apache 2.0. See [LICENSE](LICENSE).
  348. ---
  349. ## Citing
  350. If you use Agent Skills or ORCA in research, please cite:
  351. ```bibtex
  352. @article{fernandez_orca_2026,
  353. author = {Fernandez Alvarez, Guillermo E.},
  354. title = {Beyond Prompting: Decoupling Cognition from Execution in
  355. LLM-based Agents through the ORCA Framework},
  356. year = {2026},
  357. publisher = {Zenodo},
  358. doi = {10.5281/zenodo.19438943},
  359. url = {https://doi.org/10.5281/zenodo.19438943}
  360. }
  361. ```
  362. Software citation:
  363. ```bibtex
  364. @software{fernandez_agent_skills_2026,
  365. author = {Fernandez Alvarez, Guillermo},
  366. title = {Agent Skills Runtime},
  367. year = {2026},
  368. url = {https://github.com/gfernandf/agent-skills},
  369. version = {1.0.2},
  370. license = {Apache-2.0}
  371. }
  372. ```
  373. See also [CITATION.cff](CITATION.cff).
  374. ---
  375. ## Troubleshooting
  376. | Problem | Solution |
  377. |---------|----------|
  378. | Registry not found | Run doctor and ensure agent-skill-registry is cloned next to this repo |
  379. | Command not found on Windows | Use python skills.py ... from repo root |
  380. | Unexpected runtime error | Check [docs/ERROR_TAXONOMY.md](docs/ERROR_TAXONOMY.md) |
  381. | Environment mismatch | Review [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.