Welcome to Skillware. We are building an open registry of modular, deterministic agent capabilities—skills that any compatible runtime can load. Most contributors add or improve skills, but documentation, framework fixes, tests, and good first issues are equally welcome.

This document is the single entry point for how to contribute. If you are an AI agent working on this repository, read Agent Contribution Workflow first. Human operators may use the same guide to supervise agent work.

Pick the path that matches your issue. Only the skill row requires the full bundle under Skill bundle standard.

Skills remain the primary contribution we expect, but every type above should follow Getting started, Universal expectations, and Pull request process.

Check existing issues before starting work.

Issue chooser links: CONTRIBUTING, good first issues, Skill Library. Labels are defined in .github/labels.json and synced automatically on merge to main (see sync-labels workflow).

Label taxonomy: Repo-wide labels describe contribution type or area (bug, cli, security, …). Registry category labels use the cat: prefix (cat: office, cat: security, …) so they never collide with repo-wide names — for example security is for vulnerabilities and trust-model work, while cat: security filters issues about skills under skills/security/. All cat: labels share one pastel color (#E6D9F5). Maintainers may add a cat: label when triaging skill issues and PRs.

Wait for maintainer feedback on non-trivial work before investing in a large PR.

Before writing docs, read the glossary.

Fork ARPAHLS/skillware to your GitHub account, then clone your fork:

git clone https://github.com/<your-username>/skillware.git
cd skillware
git remote add upstream https://github.com/ARPAHLS/skillware.git

git fetch upstream
git checkout main
git pull upstream main
git checkout -b feat/issue-<number>-short-description

pip install -e ".[dev,all]"

For documentation-only PRs, pip install -e ".[dev]" is sufficient. For skill or framework work, use [dev,all] to match CI (optional [agents] for SDK examples — see Install extras).

Prefer a dedicated venv for clone work — full setup, sanity check, and recovery: TESTING.md — Clone dev setup.

Use one install mode per interpreter — editable or PyPI wheel, not both. Mixing pip install -e ".[dev,all]" from a clone with pip install skillware / pip install -U skillware on the same Python can leave orphan skillware-*.dist-info folders and make the CLI print skillware None / vNone (#333).

Before switching modes:

python -m pip uninstall skillware -y

Then either editable (pip install -e ".[dev,all]" from the repo) or PyPI (pip install skillware). On Windows, prefer py -3.13 -m pip (or your target version) so you do not accidentally install into a different Python.

If pip uninstall fails (uninstall-no-record-file), run skillware doctor --install for copy-paste recovery commands, or use scripts/dev_install.ps1 / scripts/dev_install.sh from a clean repo checkout.

See TESTING.md for clone dev setup and TESTING.md for the bundle / framework / maintainer / example model and pytest usage.

Follow the table in Ways to contribute, then Pull request process.

These apply to all contributions, regardless of type.

Follow the Agent Code of Conduct: deterministic skill outputs, documented dependencies, no malicious or deceptive code.

• No emojis in source code, documentation, commit messages, or PR titles.
• Use Black for formatting (CI runs black --check) and Flake8 for linting (see TESTING.md).
• Match existing naming, structure, and documentation tone in the files you touch.
• Use glossary.md terms in new prose. Inclusive language: inclusive-language.md. Do not global-replace user with operator.

• Change only what the issue requires. Avoid unrelated refactors or drive-by edits.
• Do not bump the package version in pyproject.toml (or CITATION.cff version / date-released) unless the issue or a maintainer explicitly requests it (skill-only PRs typically do not version the framework). See Maintainer: cutting a framework release.
• When a PR changes user-visible behavior (framework features, new or changed skills, breaking fixes, CLI or documentation users rely on), add entries under [Unreleased] in CHANGELOG.md in the same PR (Keep a Changelog sections: Added / Changed / Fixed / Removed). Do not add version headers or publish releases; maintainers cut releases.
• Skill-only PRs that will not ship in the next PyPI release may omit a CHANGELOG entry; ask on the issue or use maintainer judgment.

• Add or update tests in the correct layer when behavior changes (see TESTING.md).

• Skill bundle test — skills/<category>/<name>/test_skill.py (required for new skills; ships in the wheel; runs in CI via pytest skills/).

• Framework test — tests/test_*.py at repo root (loader, CLI, issuer rules, doc-drift guards).

• Maintainer skill test — optional tests/skills/<category>/test_<name>.py for extra loader or edge-case coverage.

• Usage examples — examples/*.py are not tests and are not run in CI.

• GitHub Actions runs two jobs on every PR (see .github/workflows/ci.yml):

  • build — editable install pip install -e ".[dev,all]", then python -m black --check ., flake8 ., pytest skills/ (bundle tests), pytest tests/ (framework + maintainer tests).
  • wheel-smoke — builds a wheel, installs it in a fresh venv (base deps only), runs scripts/wheel_smoke_test.py to verify every bundled registry skill ships correctly. See Packaging smoke test.

• Do not add per-skill pip lines or hardcoded skill paths to .github/workflows/ci.yml.

• Run locally before opening a PR:

  python -m black --check .
  python -m flake8 .
  python -m pytest skills/
  python -m pytest tests/

  Bundle tests can also be run with skillware test (see CLI reference); requires [dev] or [dev,all].

  For a single skill:

  python -m pytest skills/<category>/<skill_name>/test_skill.py

  Or: skillware test <category>/<skill_name>.

• Install packages from that skill's manifest.yaml requirements when they are not covered by [all]. After adding a skill with new third-party deps, run python scripts/sync_extras.py (see Install extras).

• Wait for GitHub Actions CI to pass before requesting review.

Use the pull request template. Complete the New or updated skill section only when this PR adds or changes files under skills/.

Before requesting review, verify your PR template checklist:

• Select the correct change type (skill, documentation, framework, bug fix).
• Confirm local flake8, black and pytest pass (both pytest skills/ and pytest tests/).
• Add a CHANGELOG entry under [Unreleased] when the change is user-visible.
• Fill only the checkboxes that truthfully apply; do not leave unchecked defaults.

Agents must follow Agent Contribution Workflow. Human operators: approve the agent's plan before implementation, verify tests, and own the fork, commit, and PR. The operator remains responsible for the merged diff.

1. Link an issue — Reference it in the PR description (Fixes #123 or Refs #123).

2. Fork and branch — Work on a feature branch, not main of the upstream repo.

3. Implement — Use the checklist for your contribution type (Ways to contribute).

4. Verify locally:

   python -m black --check .
   python -m flake8 .
   pytest skills/
   pytest tests/

   Or skillware test for bundle tests (see CLI reference).

   For skill work, also run:

   pytest skills/<category>/<skill_name>/test_skill.py
   pytest tests/test_skill_issuer.py

   Or skillware test <category>/<skill_name> for the bundle test only.

5. Commit — Clear imperative message, no emojis; include issue reference when appropriate. Do not add AI tools in Co-authored-by: trailers (see Agent Code of Conduct).

6. Changelog — If the PR is user-visible, add lines under [Unreleased] in CHANGELOG.md before opening the PR.

7. Push to your fork and open a PR into ARPAHLS/skillware main.

8. CI — Ensure checks pass; address review feedback on the same branch.

1. Copy or align with templates/python_skill/.
2. Create skills/<category>/<skill_name>/ with the full bundle (see Skill bundle standard).
3. Add docs/skills/<category>/<skill_name>.md, a row in docs/skills/<category>/README.md, a row in docs/skills/README.md, and a link in docs/sitemap.md.
4. When adding or renaming a runnable script under examples/, update examples/README.md in the same PR.
5. Confirm SkillLoader.load_skill("<category>/<skill_name>") works or document required packages and environment variables.

Skills you submit are reviewed for origin and quality, not sandboxed at runtime — operators run them in their own process. Understand the skill trust model before designing a skill's behavior.

Every registry skill lives in skills/<category>/<skill_name>/ and must include the files below. This is the detailed standard for the skill contribution type.

Checklists below use file names; each file implements a role. The README Mission summarizes the core roles; full reference: docs/introduction.md — Skill anatomy. Terms: glossary.md.

Effect modules (for example workflow.py, budget.py) are imported by skill.py—implementation detail, not a separate required file. Corpus tooling (for example maintenance/) refreshes Corpus offline and is not loaded by execute().

Defines the tool interface, safety constitution, dependencies, and issuer attribution.

Required fields and sections:

• name — registry skill ID in category/skill_name form; must match the folder path under skills/ (same string as SkillLoader.load_skill(...) and the CLI ID column). Do not use a short name alone (for example pdf_form_filler without the office/ prefix). The loader emits SkillwareIdentityWarning when a registry-layout skill (<skill_root>/<category>/<skill_name>/) has a missing or mismatched name (warn-only in v1; may become an error later). Flat private layouts (<skill_root>/<skill_name>/) skip this check. Enforced in CI via tests/test_registry_identity.py — mismatched or duplicate manifest.name blocks merge (#280).
• version, description
• issuer — see Issuer attribution; name and email required, github and org optional
• short_description — optional one-line summary (~80 chars) shown in skillware list when present. Keep it accurate and searchable (the problem the skill solves); do not keyword-stuff.
• parameters — valid JSON Schema for LLM tool calling
• constitution — safety boundaries enforced at the prompt level
• requirements — when external packages are needed (for example requests, pandas). Use PEP 508 strings; add version specifiers (for example web3>=6.0.0) when the skill depends on a minimum package version — SkillLoader.load_skill() validates pins at load time (see Install extras).

Optional but common:

• env_vars — API keys and configuration (never hardcode secrets in skill.py); read them with self.credential(name) (config first, then env); document names on the catalog page and link to API keys for skills
• category, outputs, presentation — when they clarify the skill contract. Use outputs: with named keys (never legacy singular output:).

Example:

name: category/generic_hello
version: 1.0.0
description: A friendly greeting skill.
issuer:
  name: Your Name
  email: you@example.com
  github: your_github_username
  org: YOUR ORG
parameters:
  type: object
  properties:
    name:
      type: string
  required:
    - name
constitution: |
  1. Do not greet offensive names.
  2. Always maintain a polite tone.
requirements:
  - requests

• Define exactly one concrete subclass of BaseSkill per skill file. SkillLoader.load_skill() discovers it automatically as bundle["class"] (see SkillLoader.get_skill_class()).
• Implement deterministic Python logic; inherit from BaseSkill.
• Expose the bundle manifest via @property def manifest(self) -> Dict[str, Any]: return self.load_manifest_from_dir(os.path.dirname(__file__)) (template: templates/python_skill/skill.py).
• Accept a dictionary of inputs; return a JSON-serializable dictionary.
• Catch internal errors and return a structured error report; do not crash the host agent.
• Do not print to stdout or stderr for normal operation.
• Do not embed open-ended LLM code generation as the skill implementation.
• When you change the JSON shape returned by execute(), update card.json output fields (if present) and the matching fixture under tests/fixtures/card_ui_schema/ in the same PR.

The primary guide for the host LLM. Skill instructions should be a concise, append-only block focusing on this skill's context rather than assigning an overarching persona (host agents and LLMs already have their own system prompts).

• Prefer skill context: Open with what the skill does, its registry ID (category/skill_name), deterministic behavior, and key limits.
• When to invoke / when not to invoke: Clearly explain primary use cases and anti-patterns.
• Outputs and errors: Detail how to interpret returned fields (image_base64, paths, structured dicts) and handle error states.
• Avoid persona starters: Avoid opening with "You are an agent equipped with...", "You are an expert...", or narrative personality instructions that can conflict when multiple skills are appended to context.
• Keep prompts and persona here, not in skill.py.

• Recommended for every registry skill; all bundled skills under skills/ ship one.
• Describes UI presentation (name, description, icon, ui_schema, and similar).
• When present, include an issuer object that matches manifest.yaml (name and email at minimum; copy github and org when used).
• For output cards (ui_schema.type = card), each ui_schema.fields[].key must be a dot path into the JSON returned by execute() (for example metadata.wallet_address, preview.you_pay). Update card.json in the same PR when you change the output shape.
• Add or refresh a representative output fixture at tests/fixtures/card_ui_schema/<category>__<skill_name>.json (one object or a {"samples": [...]} list when multiple execute paths surface different fields). CI validates keys via tests/test_card_ui_schema.py (#199).

• Required for every new registry skill (template: templates/python_skill/test_skill.py; enforced by tests/test_skill_issuer.py).
• Unit tests for schema compliance and deterministic execution paths (offline; mock externals).
• Ships inside the skill bundle via pip install skillware.
• Run: pytest skills/<category>/<skill_name>/test_skill.py or skillware test <category>/<skill_name>
• Optional extra depth for maintainers: tests/skills/<category>/test_<skill_name>.py — see TESTING.md.
• Mock network calls and first-run model downloads in bundle tests.

Not required for every skill. When present, document them on the catalog page under Bundle layout (see skill usage template).

• Corpus — kb/, data/, or other versioned knowledge files the Effect reads at runtime.
• Reference — schemas/, terminology maps, or in-bundle fixtures that define the public contract or demos.
• Effect modules — additional .py files imported only by skill.py (not separate registry roles).
• Corpus tooling — offline maintenance scripts (not loaded by execute()); keep out of the Effect import path unless intentional.

Registry skills are shipped inside the skillware wheel. Per-skill layout uses manifest.yaml and packaging hooks below — not per-skill edits to CI.

• Add an empty __init__.py in skills/<category>/ when you introduce a new category, and in skills/<category>/<skill_name>/ for each new skill directory (enforced by tests/test_skill_issuer.py).
• Non-Python files (manifest.yaml, instructions.md, card.json, data files) are included automatically via MANIFEST.in and [tool.setuptools.package-data] (skills = ["**/*"]).
• Confirm SkillLoader.load_skill("<category>/<skill_name>") works from the repo root. CI wheel-smoke verifies every bundled skill from a clean pip install of the built wheel; run scripts/wheel_smoke_test.py locally when changing packaging, MANIFEST.in, or skill bundle layout (see TESTING.md).

Manifest requirements and optional extras

• List runtime packages in the skill's manifest.yaml requirements (source of truth for loaders and docs).
• Unpinned entries (for example requests) — loader checks the importable module exists.
• Pinned entries (for example rembg>=2.0.0) — loader also verifies the installed distribution satisfies the specifier before skill.py runs. Pin when API or behavior breaks across versions; unpinned is fine for stable deps.
• Run python scripts/sync_extras.py after changing manifests — it regenerates category, per-skill, and [all] rows in pyproject.toml. Update the hand-maintained tables in Install extras in the same PR; CI guards them via tests/test_extras_sync.py::test_install_extras_guide_matches_pyproject.
• Core already includes requests, pyyaml, and beautifulsoup4 (manifests may say bs4); the sync script omits core packages from extras automatically.
• Hand-maintained extras (dev, gemini, claude, openai, bedrock, agents) stay above the generated block in pyproject.toml.
• Contributors and CI install skill runtime deps with pip install -e ".[dev,all]"; add [agents] when running SDK examples locally.

• Human-readable documentation linked from the Skill Library and the category hub docs/skills/<category>/README.md.
• Include ID, Issuer, Version (from manifest.yaml), and Recommended install (pip install "skillware[<category>_<skill>]" — see install_extras.md) near the top.
• Include the intent block (<!-- skill-intent:begin -->) with Solves, Works with, and Runtime lines so search and GitHub can match operator queries. Keep wording accurate; do not stuff keywords.
• Describe capabilities, prerequisites, arguments, and limitations.
• If the skill calls external services, list its environment variables in a short table and link to API keys for skills. Do not duplicate the full setup guide on the skill page.
• Add a Usage Examples section with runnable snippets for Gemini, Claude, OpenAI, DeepSeek, and Ollama (prompt mode). Follow skill usage example template and link to usage guides and agent loops.
• Add a Skill history section before the statutory / enterprise disclaimers: a table of notable commits that touched the skill bundle or catalog page. Link each commit SHA and list contributors as linked GitHub usernames ([@username](https://github.com/username)). Append a row when you ship a skill update in the same PR.
• Regulatory / statutory knowledge skills (for example MiCA, GDPR, EU AI Act): add a Statutory knowledge notice (## Statutory knowledge notice) immediately above Enterprise disclaimer, mirror the snapshot date and informational framing in instructions.md and manifest.yaml constitution, and expose statutory_snapshot on catalog cards when useful. Pattern: templates/python_skill/README.md (#397).

Do not add skills/<category>/README.md inside the runtime registry. Category landing pages belong under docs/skills/<category>/README.md so SkillLoader.load_skill() IDs stay stable.

• Add or update the skill table in docs/skills/<category>/README.md and docs/skills/README.md (Skill, ID, Version, Issuer, Description). Set Version to `x.y.z` (DD Mon YYYY) from the manifest and the release/merge date.
• Add the catalog page and hub to docs/sitemap.md.
• New top-level category: also add a row to the root README category table and a hub at docs/skills/<category>/README.md.

The manifest is the source of truth for issuer data. Use real contact details in everything under skills/—not template placeholders (Your Name, you@example.com, YOUR ORG, and similar).

Registry-wide issuer rules are enforced in tests/test_skill_issuer.py (skills under skills/ only; templates are excluded).

issuer.org is an optional single string for affiliation or design ownership — not necessarily who wrote every line of code. Individual credit stays in issuer.name, email, and github. Omit org when no org applies. Use comma-separated values when multiple orgs apply (for example ARPAHLS, AO).

Separate multiple orgs with a comma in the single org string (for example org: ARPAHLS, AO). Match the catalog Issuer line to the manifest value.

Place each skill under one top-level directory under skills/. Use an existing category when it fits.

The table above is illustrative, not a closed list. When contributing a new skill, pick the category whose purpose best matches the skill's primary function.

Registry IDs are always category/skill_name from the folder path and must match the name field in manifest.yaml (same string as SkillLoader.load_skill(...) and the CLI ID column). For the live registry, see Skill Library.

New top-level category? Open an issue and discuss with maintainers before adding a folder — do not create skills/<new_category>/ in a pull request without that agreement.

When a new top-level category lands under skills/, update this table and the category dropdown in .github/ISSUE_TEMPLATE/01_skill_proposal.yml in the same PR. Add a matching cat: <category> entry to .github/labels.json (same pastel color as other cat: labels; never use the bare folder name as a repo-wide label). Update REGISTRY_CATEGORIES in tests/test_github_labels.py in the same PR. Add docs/skills/<category>/README.md, a root README category table row, and a sitemap section. Labels sync via CI on merge to main. Do not add a README.md under skills/<category>/.

• God skills — One skill that does everything; split into focused capabilities.
• Hardcoded models — Do not hide prompts in skill.py; use instructions.md.
• Vendor lock-in — Prefer standard Python over framework-specific wrappers in skill logic.
• Environment leaks — No API keys in source; document env_vars in the manifest.
• Placeholder issuers — No template names or emails in committed registry skills.
• Unrequested version bumps — Do not change pyproject.toml version in routine skill PRs.

• Skills that touch real-world assets (wallets, email, production APIs) should support a dry run or read-only mode when feasible. High-risk skills (on-chain transfers, wallet operations) should use preview and confirmation flows before sending transactions; read each skill's instructions before enabling live keys.
• Sanitize inputs in skill.py before external calls.
• Respect the skill constitution in both code and documentation.
• Malicious or deceptive contributions may be rejected and blocked from the project.
• Registry review is not runtime isolation. Passing maintainer review means a skill's origin is trusted; it does not sandbox the skill. All skills run in the host process regardless of tier. See the skill trust model.

By submitting a Pull Request to this project, you explicitly certify, represent, and agree that:

1. Original Authorship & Authority: The contribution is your own original creation, or you have verified that you possess the full legal authority and rights to submit it under the project's existing MIT License.
2. Permanent Irrevocable License: You grant ARPA Hellenic Logical Systems and project maintainers a permanent, worldwide, non-exclusive, royalty-free, irrevocable, and sublicensable license to use, modify, adapt, prepare derivative works of, publicly display, publish, and distribute your code across all present and future releases of Skillware.
3. Non-Revocability: You understand and agree that once merged into the repository, contributions cannot be retroactively revoked, clawed back, or forced to be deleted from git commit history or distribution packages.
4. Patent Non-Assertion: You grant a royalty-free, perpetual patent license covering any patent claims you own, control, or license that are necessarily infringed by your contribution when combined with Skillware.
5. No Malicious Logic or Undeclared Telemetry: You warrant that your submission does not contain malicious logic, unauthorized credential exfiltration routines, hidden telemetry backdoors, or undisclosed third-party proprietary materials. All runtime credentials must be declared via manifest env_vars and resolved through BaseSkill.credential().
6. Third-Party Rights & Contributor Responsibility: You represent and warrant that your submission does not copy, incorporate, or infringe upon any confidential, proprietary, or copyrighted code from your employer, former employers, or third parties without explicit authorization. You acknowledge that you remain personally responsible and legally liable for any willful misrepresentation or intellectual property infringement in your contribution.

Routine contributor PRs must not bump the package version. Maintainers cut releases (chore / release PR or direct maintainer commit) and should keep version surfaces in sync:

Maintainer release preparation and documentation curation must always be conducted through manual, line-by-line inspection and editing. Never use automated batch scripts to update documentation, changelogs, or skill histories. Comparing past commits (git log -p -- <skill_dir>) and CHANGELOG.md ensures zero template placeholders, accurate commit numbers, and precise author attribution across every catalog page.

README Citing badge and pyproject.toml [project.urls] DOI already point at the concept DOI. Do not add .zenodo.json unless a Zenodo-only field is required (it would override CFF).

Thank you for helping make agent capabilities portable, safe, and reusable.