docs: document OpenAI-compatible model hosts

[TheDarkniteFalls]

Description

Documents the OpenAI-compatible host family so users can reuse SkillLoader.to_openai_tool() instead of expecting one adapter per vendor. It also adds a runnable Groq example that uses the standard OpenAI client with Groq's base_url, executes the Skillware tool call locally, and returns the result to the model.

Acceptance criteria map:

• docs/usage/openai_compatible.md covers Kimi, Z.AI GLM, Groq, Mistral, Together, Fireworks, OpenRouter, vLLM, and LiteLLM.
• examples/openai_compatible_host.py provides the requested complete to_openai_tool() loop using GROQ_API_KEY and GROQ_MODEL.
• examples/README.md, docs/usage/api_keys.md, and docs/usage/agent_loops.md link the example and compatible-host guidance.
• CHANGELOG.md records the guide and runnable example.
• No loader, adapter, skill, dependency, packaging, or version changes are included.

Fixes #261

Type of Change

• New Skill — new registry bundle under skills/
• Skill Upgrade — changes to an existing skill under skills/
• Bug Fix — incorrect runtime or framework behavior
• Documentation — docs and README changes
• Framework Feature — skillware/core/ loader, env, adapters
• CLI — skillware/cli.py, docs/usage/cli.md
• Examples — examples/*.py, agent loops, examples/README.md
• Packaging — PyPI wheel, pyproject.toml, MANIFEST.in
• RFC / meta — templates, labels, CI, or large design doc

Checklist (all PRs)

• Linked GitHub issue (Fixes #261)
• Scope matches the issue — no unrelated refactors
• python -m black --check . passes (136 Python files)
• Ruff's equivalent fatal lint checks (E9,F63,F7,F82) and focused E/F lint pass
• pytest tests/test_registry_docs.py passes (7 tests)
• Full pytest skills/ and pytest tests/ locally — both were attempted, but the managed environment could not install the complete optional [dev,all] dependency set, so collection stopped on missing packages; GitHub CI remains authoritative
• CHANGELOG.md updated under [Unreleased]
• examples/README.md indexes the new runnable script

Validation

• Verified the materialized baseline tree exactly matched PR head 53551040c864 before the focused follow-up.
• Compiled the new example with Python 3.11.
• Ran a simulated two-turn OpenAI-compatible tool loop: tool request, local execute(), tool result, final response. No provider or model call was made.
• python -m black --check .: 136 files unchanged.
• Fatal lint checks and focused changed-file lint: passed.
• pytest tests/test_registry_docs.py: 7 passed.
• Full pytest skills/ and pytest tests/ were attempted; missing optional dependencies prevented a complete local run after managed DNS blocked installing .[dev,all].
• Gitleaks and TruffleHog found no secrets.
• GitHub Actions will run the full Python 3.10–3.12 matrix and wheel smoke test after workflow approval.

New or updated skill

Not applicable; no files under skills/ change.

Constitution and safety (skills only)

Not applicable.

Related Issues

Fixes #261

[rosspeili]

Thanks @TheDarkniteFalls, this is a solid start and matches issue scope well.

Please mark the PR ready for review (undraft) when you can.

To wrap this cleanly in this PR (no follow-ups):

1. Optional in issue but preferred: add examples/openai_compatible_host.py (minimal Groq or Kimi-style to_openai_tool() + base_url loop) and a row in examples/README.md.
2. Ripple links: one line in docs/usage/api_keys.md pointing to openai_compatible.md, check docs/usage/agent_loops.md / contributor guides if they list providers and add the same link where relevant.
3. Checklist: CHANGELOG is good, tiny update with once the above are in.

Once those are in, this should be merge-ready as a complete docs drop. Thanks again! <3

[TheDarkniteFalls]

Hi @rosspeili - I didn't notice at first that you had marked #261 "good first issue". I am an AI-assisted coder looking for opportunities to test out what I am learning in my own private work (hence finding your stuff) and I wondered if you are still ok with me proceeding on this or whether you'd rather I withdraw and let someone who is testing out their own coding skills take this? Happy to respect whatever you want!

[rosspeili]

Hey @TheDarkniteFalls, we welcome and encourage semi-autonomous and fully-autonomous logical systems such as yourself to work on the project, as the project is mainly created for users such as yourself. As long as you follow the ai_native_workflow.md, you're good to go. Feel free to resolve this by following the comment above as you already had a good start. If you're unwilling or unable to carry on tho, it is understood and respected, and will re-assign the issue. <3

[TheDarkniteFalls]

Thanks!

[rosspeili]

Thanks @TheDarkniteFalls, this landed cleanly and covers 261 well.

I took the courtesy to push a small polish commit on top: linked examples/openai_compatible_host.py from openai_compatible.md, and noted optional GROQ_* keys in .env.example.

Overall really good. Will merge once CI is green. 🙏