[Docs]: add dedicated skill chaining guide under docs/usage

[rosspeili]

Type of fix

Other

What needs to be fixed?

Skill chaining is mentioned in fragments but never documented as a first-class usage pattern.

Current state (scattered):

• docs/usage/gemini.md — short “Skill Chaining (Middleware)” section with one example: optimization/prompt_rewriter → optimized system context before Gemini ([Feat]: cli skillware examples command and list --examples coverage flag #126-era).
• docs/usage/agent_loops.md — single-skill load → execute loop; examples/ollama_skills_test.py noted as multi-skill harness (model selects among tools — not the same as a deterministic host pipeline).
• docs/skills/README.md — “Middleware” category description; individual skill pages (e.g. prompt_rewriter, token_limiter) mention orchestrator/host roles in isolation.
• docs/vision.md / README.md — “skill chain” in vision/enterprise prose only; no operator how-to.
• No docs/usage/skill_chaining.md (or equivalent).

Problem: Contributors and operators cannot find guidance on composing multiple skills in one workflow — especially middleware (firewall, token limiter, prompt compressor) with domain skills (mail, wallet screening, etc.). New skills like office/gmail_handler (#291) increase the need for clear chaining patterns.

Request: Add a dedicated usage guide that explains how chaining works in Skillware (host/agent owns order; each skill is deterministic execute(); no built-in chain runner in the framework; optional validate_params; context carry-forward where skills support it e.g. gmail context).

Proposed new page: docs/usage/skill_chaining.md

Content outline:

1. Concepts — sequential host pipeline vs multi-tool LLM loop vs middleware pre/post-processing; when to use each.
2. Rules of thumb — fail-closed middleware, untrusted input handling, secrets/env, constitution order, token budget gates.
3. Minimal pattern — load N skills, host Python orchestrates execute() calls, pass JSON between steps (pseudocode + one small real snippet).
4. At least 5 worked examples (progression simple → complex):
   • 2-chain (basic): optimization/prompt_rewriter → feed compressed_text into model context (extend existing gemini.md idea; provider-agnostic).
   • 2-chain (security): security/prompt_injection_firewall → sanitize untrusted text before any LLM or downstream skill (e.g. scraped page, email body).
   • 2-chain (budget): host loop + monitoring/token_limiter gate each turn before calling the model (align with examples/token_limiter_loop.py).
   • 3-chain: firewall → prompt_rewriter → domain skill input (compress only after sanitize).
   • 3-chain (agent + mail): office/gmail_handler read_message → firewall on body → agent drafts → preview_send / send with confirmation (reference gmail context carry-forward).
   • 4-chain (optional stretch): untrusted inbound → firewall → pii_masker → rewriter → LLM — document trade-offs (latency, false positives).
5. Multi-tool vs chain — clarify examples/ollama_skills_test.py (model chooses tool) vs explicit host ordering.
6. Cross-links — from docs/usage/README.md, docs/usage/agent_loops.md, and trim/redirect gemini.md chaining section to the new guide (keep a short pointer + link, avoid duplication).

Non-goals (this issue):

• New framework API for chains (RFC material if ever needed).
• New runnable examples under examples/ (optional follow-up; doc can use inline snippets referencing existing scripts where they exist).

Acceptance criteria:

• docs/usage/skill_chaining.md published with concepts + ≥5 chain examples (2-skill and 3+ skill).
• docs/usage/README.md indexes the new guide.
• docs/usage/agent_loops.md links to skill chaining for multi-step workflows.
• docs/usage/gemini.md chaining section shortened to pointer + link to new guide.
• CHANGELOG.md [Unreleased] entry.
• pytest tests/test_registry_docs.py passes if link/index guards apply.

Affected Page(s)

docs/usage/skill_chaining.md (new), docs/usage/README.md, docs/usage/agent_loops.md, docs/usage/gemini.md, CHANGELOG.md

[rosspeili]

Scope expansion (maintainer) — chaining + loading + instructions

The original outline is good. Please fold in one more thread: how skills are loaded vs how they enter model context, and how hosts should compose instructions.md in multi-skill / chain setups. Goal: one minimal guide so operators don’t assume pip install skillware[all] auto-injects every skill’s mind into the LLM.

---

Add to docs/usage/skill_chaining.md — new section 0 (before concepts)

Title: ## Loading vs context (read this first)

Bullet the facts Skillware does not spell out today:

1. pip install / [all] — skills live on disk (bundled under site-packages/skills/ or local ./skills/). Zero LLM context cost until the host calls SkillLoader.load_skill(id).
2. load_skill() — returns manifest, instructions (full instructions.md), class, adapters, etc. Loading ≠ injecting; the host decides what goes to the model.
3. Tool wiring — to_*_tool(bundle) uses manifest.description + parameters only. instructions.md is separate and must be passed explicitly (system / system_instruction).
4. Skills never call each other — chains are host Python (or agent orchestration), not a built-in chain runner.

Short diagram or table: disk → load_skill → {execute only | wire tool + optional instructions → model}.

Cross-link: agent_loops.md (single-skill loop), README.md path resolution, skill trust model.

---

Add to same guide — section on instructions composition

Title: ## When to pass instructions (single / multi-tool / chain)

Three cases — keep it prescriptive:

Pattern	What to put in system context	When
Single-skill agent loop	Full bundle["instructions"] for that skill	Default; one tool + one mind
Multi-tool loop (model picks tool)	Merged instructions or active-skill-only (see below)	examples/ollama_skills_test.py pattern
Host pipeline chain	Usually no skill instructions between deterministic execute() steps — pass JSON; inject instructions only where the model must route the next tool	firewall → rewriter → domain skill

Rules of thumb (minimal):

• ≤3 skills in one LLM session: merge with a standard header per skill, e.g. ## Skill: category/skill_name, then paste that skill’s instructions.md. Host system prompt stays primary; skill blocks append, no skill-level persona (per CONTRIBUTING §instructions.md).
• Many skills / registry browsing: do not concatenate every instructions.md. Register all tools; inject full instructions only for the skill being invoked (or use short_description + “when to invoke” from catalog until needed).
• Deterministic chains: host orchestrates execute(); only the LLM-facing step needs that skill’s instructions + tool schema.
• Middleware first: security/compliance skills (firewall, PII, token limiter) run in host order before domain skills see untrusted text — document order explicitly.

Clarify multi-tool vs chain (existing issue item, sharpen):

• ollama_skills_test.py — model chooses among tools; instructions are concatenated into one system string. Note: refresh example to use skill-context headers, not a generic “You are an intelligent agent…” wrapper (conflicts with append-only guidance).
• Host pipeline — you choose order; model may not be involved between steps.

Non-goal (this issue): new SkillLoader.compose_system_context() API — optional follow-up RFC. Doc can show a 5-line host helper as pseudocode only.

---

Original outline — keep, minor additions

1. Concepts — unchanged; add the loading vs context distinction above as §0.
2. Rules of thumb — add instruction-composition + “fail-closed middleware runs before LLM sees untrusted input”.
3. Minimal pattern — load N skills, host orchestrates execute(), JSON handoff; note: chain steps 1..N-1 often need no instructions in the model at all.
4. ≥5 worked examples — keep list; for each, add one line: “Instructions in this chain: …” (e.g. rewriter chain: no domain instructions until domain tool is wired; gmail 3-chain: gmail instructions when model handles mail actions, firewall none in system if host runs it deterministically).
5. Multi-tool vs chain — keep + ollama note above.
6. Cross-links — extend:

File	Change
docs/usage/skill_chaining.md	New — full guide
docs/usage/README.md	Index + 1-line blurb (loading vs context)
docs/usage/agent_loops.md	Link to chaining guide; short “multi-step workflows” pointer; clarify step 4 (instructions) applies per active skill in multi-tool setups
docs/usage/gemini.md	Shorten §Skill Chaining to pointer + link (keep one-line teaser)
CONTRIBUTING.md §instructions.md	One bullet: multi-skill hosts should merge with ## Skill: id headers; avoid persona starters because blocks append
docs/contributing/ai_native_workflow.md	Optional single cross-link under “Related documents”
CHANGELOG.md	[Unreleased] docs entry

Optional (nice): examples/README.md one sentence under multi-skill row: “multi-tool harness ≠ deterministic chain — see skill_chaining.md”.

---

Updated acceptance criteria

• docs/usage/skill_chaining.md includes Loading vs context + When to pass instructions + original concepts + ≥5 chain examples (each notes instruction policy).
• docs/usage/README.md, agent_loops.md, gemini.md updated and cross-linked.
• CONTRIBUTING (or ai_native_workflow) mentions append-only / multi-skill merge convention.
• pytest tests/test_registry_docs.py passes.
• CHANGELOG.md [Unreleased] entry.

Still out of scope: framework chain runner, new runnable examples (optional follow-up), compose_system_context() in core.

---

This keeps #297 as docs-only, host-owned orchestration, but closes the gap we hit in review: operators installing [all] or wiring many skills need a single place that says load on disk → inject only what you need → chain in Python → merge minds carefully.