Skip to content

Document append-only skill context #259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Dodothereal wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document append-only skill context #259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 6 additions & 5 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
2 changes: 1 addition & 1 deletion docs/contributing/ai_native_workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@rosspeili rosspeili Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

host agents might already inherit system prompts and persona beyond Skillware

- Never commit secrets; document `env_vars` in the manifest

### Core framework (`skillware/core/`)
Expand Down
12 changes: 9 additions & 3 deletions templates/python_skill/instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,20 @@
# Instructions: My Awesome Skill
# My Awesome Skill (`category/my_awesome_skill`)

@rosspeili rosspeili Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instructions for using My Awesome Skill ('cateogory/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.]

@rosspeili rosspeili Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would keep the old line, or if you wanna keep it: Describe what this skill does, eg. You are equipped with My Awesome Skill...


### 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

@rosspeili rosspeili Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need a better way to make it broad. See how skills work now. In most cases knowing which function to call and when is enough. Write it in a way that would help new skill creators to get an idea and adjust it to their skill.

- 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].

@rosspeili rosspeili Jul 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can leave this as was, no need to restate avoiding using persona, already above.


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")`