From 4535e8ccd39f9f4fa25b6f1ecbcf3dee105433b4 Mon Sep 17 00:00:00 2001 From: Dodothereal <129273127+Dodothereal@users.noreply.github.com> Date: Thu, 16 Jul 2026 21:17:41 +0200 Subject: [PATCH] Document skill-context instructions Fixes #258 Assisted-by: Claude Code --- CHANGELOG.md | 4 ++++ CONTRIBUTING.md | 11 ++++++----- docs/contributing/ai_native_workflow.md | 2 +- templates/python_skill/instructions.md | 12 +++++++++--- 4 files changed, 20 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 63c39c9..2cc56d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ Contributors add user-facing entries under `[Unreleased]` in the same PR. Mainta ## [Unreleased] +### Changed + +- **Documentation:** Clarified that skill `instructions.md` files provide concise, append-only skill context rather than host-agent personas (#258). + ## [0.4.5] - 2026-07-16 ### Added diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fca1eeb..ba06a23 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -272,12 +272,13 @@ requirements: ### 3. `instructions.md` (cognition) -The primary guide for the host LLM. +The primary guide for the host LLM. Treat it as a short, append-only block of context for this skill: host agents already own their system prompt and persona. -- Open with context such as: "You are an agent equipped with [Skill Name]..." -- Explain **when** to invoke the tool. -- Explain how to interpret outputs and handle edge cases. -- Keep prompts and persona here, not in `skill.py`. +- Open with the skill's ID, purpose, and important limits. +- Explain **when** to invoke the tool, which inputs fit each scenario, and how to interpret outputs and errors. +- Keep the guidance concise because operators may load multiple skills. +- Avoid persona assignments such as "You are an agent equipped with...", restating host-wide policies, or instructions that could conflict with another skill. +- Keep skill-specific prompts here, not in `skill.py`. ### 4. `card.json` (presentation) diff --git a/docs/contributing/ai_native_workflow.md b/docs/contributing/ai_native_workflow.md index 67c4af6..0065028 100644 --- a/docs/contributing/ai_native_workflow.md +++ b/docs/contributing/ai_native_workflow.md @@ -243,7 +243,7 @@ These align with [CONTRIBUTING.md](../../CONTRIBUTING.md). Violations block merg - On each catalog page, add a **Usage Examples** section (Gemini, Claude, OpenAI, DeepSeek, Ollama prompt mode) per [skill usage template](../usage/skill_usage_template.md). Keep provider mechanics in `docs/usage/`; put skill-specific paths, sample user messages, and `execute` payloads on the skill page. - Categories: `compliance`, `creative`, `data_engineering`, `defi`, `dev_tools`, `finance`, `monitoring`, `office`, `optimization`, `wellness` — see [Skill library](../skills/README.md) for the live registry; [Choosing a category](../../CONTRIBUTING.md#choosing-a-category) in CONTRIBUTING.md (issue first for new top-level folders) - Do not bump `pyproject.toml` version in skill-only PRs unless requested -- Logic in `skill.py`; prompts and persona in `instructions.md` +- Logic in `skill.py`; skill-specific context in `instructions.md`. Keep instructions short and append-only: host agents already own their system prompt and persona, so describe this skill's use, limits, outputs, and errors instead of assigning a role. - Never commit secrets; document `env_vars` in the manifest ### Core framework (`skillware/core/`) diff --git a/templates/python_skill/instructions.md b/templates/python_skill/instructions.md index 72c85bb..4a89604 100644 --- a/templates/python_skill/instructions.md +++ b/templates/python_skill/instructions.md @@ -1,14 +1,20 @@ -# Instructions: My Awesome Skill +# My Awesome Skill (`category/my_awesome_skill`) -You are an agent equipped with the **My Awesome Skill**. +[Describe what this skill does, whether it is local or deterministic, and important limits.] ### When to use this tool - Use this tool when the user asks for [describe primary use case]. - Do not use this tool for [describe anti-patterns]. +### How to use this tool +- Use `param1` when [describe scenario]. +- Use `param2` when [describe scenario]. + ### How to interpret the output - The tool returns a `result` field containing [describe result]. -- If you see an error message, explain to the user that [describe error handling]. +- If you see an error message, [describe the host's next step]. + +Keep this guidance focused on the skill. It is appended to the host agent's context, so do not assign a persona, restate host-wide policies, or add a long playbook. ### Examples - User: "Run my awesome skill with value X" -> Call `my-awesome-skill(param1="X")`