diff --git a/CHANGELOG.md b/CHANGELOG.md index d08423e..d44743a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ Contributors add user-facing entries under `[Unreleased]` in the same PR. Mainta ### Added - **`finance/uk_companies_house_handler`**: New skill for UK Companies House REST API — deterministic company search, profile, officers, PSC, filing history, and intent-to-operation mapping with UK corporate terminology translation; bundled endpoint index and terminology map; status-based response envelope (ready/needs_input/error) with disambiguation support. +- **Documentation**: Add minimal Mermaid architecture flow diagrams to README, introduction, and agent loops; add cross-links and direct-path footnotes (#210). ### Changed diff --git a/README.md b/README.md index 236ab6e..84cccaa 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@
Mission • + How it works • Architecture • Quick Start • Documentation • @@ -48,6 +49,18 @@ A **Skill** in this framework provides everything an Agent needs to master a dom Browse capabilities by category in the [Skill library](docs/skills/README.md) or on our site ↗. +## How it works + +```mermaid +flowchart LR + Registry[(Registry / Disk)] -->|Load| Skillware[Skillware Loader] + Skillware -->|Adapt| Host[Host App] + Host -->|Prompt + Tools| Model([AI Model]) + Model -->|Tool Call| Host +``` + +Install the registry once. Skillware loads a bundle and adapts it to your model's tool format — you run the loop. For details on how the loader turns the manifest into a tool, see the [Introduction](docs/introduction.md). + ## Architecture This repository is organized into a core framework, a registry of skills, and diff --git a/docs/introduction.md b/docs/introduction.md index 6ae4a9d..07d5a66 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -49,13 +49,47 @@ Skillware/ └── loader.py # The engine that bridges the skill to the LLM ``` +```mermaid +flowchart TD + subgraph Bundle["Skill Bundle Folder"] + Manifest[manifest.yaml] + Instructions[instructions.md] + SkillPy[skill.py] + CardJson["card.json (optional)"] + end + + Loader[SkillLoader] -->|Loads| Bundle + Loader --> Adapters + + subgraph Adapters["Model adapters"] + direction LR + G[Gemini] + C[Claude] + O[OpenAI] + OL[Ollama] + end + + Host[Host App] -.->|Directly calls execute| SkillPy + + style Host stroke-width:2px,stroke-dasharray: 5 5 +``` + +A skill is a folder on disk. The loader turns the manifest into whatever tool schema your runtime expects. For the high-level picture, see [How it works](../README.md#how-it-works); for the code loop that hooks these adapters up, see [Agent Loops](usage/agent_loops.md). + When you run `SkillLoader.load_skill("category/skill_name")`, a complex orchestration happens behind the scenes: ### Step 1: Discovery & Loading The loader resolves `category/skill_name` to a skill directory by checking, in order: an existing path on disk, roots in `SKILLWARE_SKILL_PATH`, a `skills/` folder in the current working directory (or its parents), then bundled skills installed with the package. Each bundle is a directory containing `manifest.yaml` and `skill.py`. * It dynamically imports the `skill.py` module and auto-discovers the single `BaseSkill` subclass as `bundle["class"]` (no hardcoded class names required). * It parses the `manifest.yaml` (including `issuer` for attribution, separate from tool-calling fields). Registry skills set `name` to the full ID (`category/skill_name`), which Gemini and Claude use as the tool name; OpenAI and DeepSeek receive a sanitized variant (slashes → underscores). For registry-layout paths (`///`), the loader warns when `name` does not match the folder path; flat private layouts (`//`) skip this check. Loaded bundles expose `registry_id` when validation applies. -* It reads `instructions.md` and `card.json`. +* It reads `instructions.md` and, when present, optional `card.json`. + +```mermaid +flowchart LR + ID[category/name] --> FIND[resolve] + FIND --> PACK[bundle] + PACK --> ADAPT[adapt] +``` For how skills are resolved on disk, the provenance tiers, and what to check before loading skills you did not write, see [Skill trust model & operator security](security/skill-trust-model.md). diff --git a/docs/usage/agent_loops.md b/docs/usage/agent_loops.md index 64be52c..d987ceb 100644 --- a/docs/usage/agent_loops.md +++ b/docs/usage/agent_loops.md @@ -2,12 +2,52 @@ Every integration follows the same execution pattern: +```mermaid +flowchart TD + subgraph Skillware + Load((1. Load)) --> Adapt((2. Wire / Adapt)) + end + + subgraph Model + Prompt((3. Prompt)) + Return((5. Return)) + end + + subgraph Host ["Host App"] + Execute((4. Execute)) + end + + Adapt -->|Inject tools/instructions| Prompt + Prompt -->|Tool call request| Execute + Execute -->|Tool result JSON| Return + Return -->|Loop next iteration| Prompt +``` + +Your loop always looks like this. Skillware handles load and tool translation; you call execute and pass JSON back. To see what files a skill contains, see the [Introduction](../introduction.md). + 1. `bundle = SkillLoader.load_skill("/")` 2. `skill = bundle["class"]()` — or `SkillLoader.get_skill_class(bundle)()`; `bundle["module"]` remains available for backward compatibility. 3. Adapt `bundle` for the model (`to_gemini_tool`, `to_claude_tool`, etc.). 4. Pass `bundle["instructions"]` as system context. 5. On tool call, `result = skill.execute(arguments)` and return JSON to the model. +| Step | Call | +| :--- | :--- | +| **load** | `SkillLoader.load_skill(id)` | +| **wire** | `to_*_tool(bundle)` + `bundle["instructions"]` → model | +| **prompt** | User query → model | +| **execute** | `bundle["class"]().execute(args)` | +| **return** | Tool result → model | + +### Direct path (no model) + +You can also run skills directly without an LLM or agent loop (e.g., `examples/token_limiter_loop.py`): load the skill, call `execute(args)` directly, and process the returned JSON. + +```mermaid +flowchart LR + Load((1. Load)) --> Execute((2. Execute)) --> JSON((3. JSON)) +``` + Provider guides contain full API details. Skill pages contain copy-paste examples with skill-specific paths and sample user messages. ---