docs: add minimal architecture flow diagrams to README, introduction,…

[meghana922007]

Description

This PR implements the following updates to the documentation as requested in the review comments:

1. Agent Loops Diagram & Table Updates (docs/usage/agent_loops.md):

   • Refactored the core agent loops flowchart to explicitly show the division of responsibilities: Skillware (loading & adaptation), Host App (local execution), and the AI Model (prompting, cognition, and return/synthesis).
   • Fixed the step table in agent_loops.md to use the correct bundle["class"]().execute(args) format instead of the outdated SkillClass().execute(args) to match step 2.
   • Added a mini Mermaid flowchart representing the direct execution path (Load ➔ Execute ➔ JSON) for direct integrations without an LLM.

2. Introduction Flowchart Updates (docs/introduction.md):

   • Updated the "Skill Bundle Folder" flowchart subgraph to include card.json as an optional bundle file alongside manifest.yaml, instructions.md, and skill.py.

Type of Change (Matches Issue Templates)

• Skill Proposal: New Skill (Contains manifest.yaml, skill.py, and instructions.md)
• Bug Report Fix: Non-breaking change which fixes an execution error or framework bug
• Doc Fix: Documentation Update
• Framework Feature / RFC Updates: Core Framework Update (Changes to base_skill.py, loader.py, etc.)

Checklist (all PRs)

• My code follows the Agent Code of Conduct.
• I have run python -m flake8 ., pytest skills/ (or skillware test), and pytest tests/ locally (or the subset relevant to this change).
• CHANGELOG.md updated under [Unreleased] if this PR changes user-visible behavior.
• examples/README.md is updated if this PR adds, renames, or removes a runnable script under examples/.

Related Issues

Fixes #210

[rosspeili]

Thanks for picking up #210, @meghana922007, the diagrams are a solid start.

Before merge, a few tweaks:

1. PR description, please fill in the template (summary, tick Doc Fix + checklist, Fixes #210) now it seems the description is cut at top.
2. agent_loops.md, step table: use bundle["class"]().execute(args) to match step 2 (not SkillClass()).
3. Agent loops diagram, add Skillware (and ideally Model) so the picture matches the issue: Skillware handles load/adapt; host runs execute.
4. Optional from issue, mini Mermaid for direct path (load → execute → json); mention card.json in the intro bundle box if easy.

Happy to merge after those, nice first docs contribution <3

[rosspeili]

Thanks @meghana922007, great work on #210 and the review follow-up.

I pushed one small maintainer commit on your branch so we can merge without a follow-up docs PR:

• card.json (optional) in the bundle diagram, matches our docs: required files are manifest.yaml + skill.py; card.json is catalog/UI metadata when present
• Step 1 mini-pipeline (category/name → resolve → bundle → adapt), visual for what load_skill() does, per [Docs]: Add minimal architecture flow diagrams to README, introduction, and agent loops #210
• Adapter fan-out (Gemini / Claude / OpenAI / Ollama), aligns with Step 2’s to_*_tool list instead of a generic “Model Tool Schemas” box
• Direct-path Mermaid moved out of the blockquote, more reliable GitHub rendering
• Intro → README #how-it-works cross-link, completes the three-page link triangle

We’ll merge once CI is green. Very nice first contribution <3 Congrats!

[meghana922007]

Thank you so much for the detailed feedback and for taking the time to polish the diagrams! I really appreciate all the guidance throughout the review process. This was a great learning experience, and I’m excited to contribute more in the future.

[rosspeili]

The pleasure was mine @meghana922007. Please feel free to explore more good first issues around docs or other sections if you want. Happy to assign to you low hanging fruits.