Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
358 lines (255 loc) · 17.7 KB

CONTRIBUTING.md

File metadata and controls

358 lines (255 loc) · 17.7 KB

Contributing to Skillware

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.

Navigation

Section Description
Ways to contribute Choose your contribution type
Getting started Fork, branch, install, open issues
Universal expectations Standards that apply to every PR
Pull request process From issue to merge
Skill Package Standard Required layout for registry skills
Skill categories Folder taxonomy under skills/
What to avoid Anti-patterns
Safety and security High-risk skills
Related documents Code of conduct, testing, templates

Ways to contribute

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

Type What you change Typical issue label Before coding Verify locally
New or updated skill skills/<category>/<name>/, docs/skills/, templates Skill proposal, enhancement Skill proposal or approved issue Bundle test + pytest tests/test_skill_issuer.py (see TESTING.md)
Documentation docs/, README.md, CONTRIBUTING.md Documentation, good first issue Doc issue or typo/fix issue Links valid; tone consistent
Core framework skillware/core/, tests/ Framework feature Framework feature issue pytest tests/; update usage docs if API changes
Bug fix Paths named in issue Bug report Reproduction or failing test Targeted test + full pytest tests/ when touching shared code
Good first issue Usually docs, tests, or small fixes Good first issue Read acceptance criteria literally Checklist for underlying type above
RFC / large change Architecture, manifest contract, loader RFC Maintainer discussion on issue Per RFC scope

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

Getting started

1. Find or open an issue

Check existing issues before starting work.

Intent Issue template
New capability in the registry Skill proposal
Loader, adapters, base_skill Framework feature
Incorrect behavior Bug report
Large or breaking design RFC

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

2. Fork and clone

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

3. Sync and branch

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

4. Install dependencies

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

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

5. Implement and verify

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

Universal expectations

These apply to all contributions, regardless of type.

Code of conduct

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

Style

  • No emojis in source code, documentation, commit messages, or PR titles.
  • Use Black for formatting and Flake8 for linting (see TESTING.md).
  • Match existing naming, structure, and documentation tone in the files you touch.

Scope

  • Change only what the issue requires. Avoid unrelated refactors or drive-by edits.
  • Do not bump the package version in pyproject.toml unless the issue or a maintainer explicitly requests it (skill-only PRs typically do not version the framework).
  • 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.

Tests and CI

  • 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).

  • 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 installs pip install -e ".[dev,all]", runs python -m black --check ., then flake8 ., then pytest skills/ (bundle tests), then pytest tests/ (framework + maintainer tests). 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/

    For a single skill:

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

  • 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, update the matching optional extra and [all] in pyproject.toml (see Packaging).

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

Pull request template

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

AI agents and operators

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.

Pull request process

  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/

    For skill work, also run:

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

  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.

Skill-specific steps (in addition to the above)

  1. Copy or align with templates/python_skill/.
  2. Create skills/<category>/<skill_name>/ with the full bundle (see Skill Package Standard).
  3. Add docs/skills/<skill_name>.md and a row in docs/skills/README.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.

Skill Package Standard

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.

1. manifest.yaml (metadata and governance)

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

Required fields and sections:

  • name, 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
  • 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)

Optional but common:

  • env_vars — API keys and configuration (never hardcode secrets in skill.py); document the same names on the skill catalog page and link to API keys for skills
  • category, outputs, presentation — when they clarify the skill contract

Example:

name: 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

2. skill.py (logic)

  • Implement deterministic Python logic (planned: inherit from BaseSkill where applicable).
  • 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.

3. instructions.md (cognition)

The primary guide for the host LLM.

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

4. card.json (presentation)

  • Optional but recommended for user-facing agents and catalog UIs.
  • 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).

5. test_skill.py (bundle test)

  • Required for every new registry skill (template: templates/python_skill/test_skill.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
  • Optional extra depth for maintainers: tests/skills/<category>/test_<skill_name>.py — see TESTING.md.

Packaging (PyPI and pip install)

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 and, when changing the loader, from a clean pip install of the built wheel.

Manifest requirements and optional extras

  • List runtime packages in the skill's manifest.yaml requirements (source of truth for loaders and docs).
  • Mirror any package not already in core [project.dependencies] into [project.optional-dependencies] in pyproject.toml: use an existing group when it fits ([gemini], [office], [defi], [embeddings], …) and always add the same pins to [all].
  • Core already includes requests, pyyaml, and beautifulsoup4 (manifests may say bs4).
  • Contributors and CI install everything needed for bundle tests with pip install -e ".[dev,all]".

6. docs/skills/<skill_name>.md (catalog page)

  • Human-readable documentation linked from the Skill Library.
  • Include ID and Issuer near the top (for example linked GitHub handle and optional org).
  • 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.

7. Registry index row

Issuer attribution

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

Field Required Notes
issuer.name Yes Display name of the contributor or maintainer
issuer.email Yes Contact email for the skill author
issuer.github No GitHub username without @
issuer.org No GitHub organization or affiliation

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

Skill categories

Place each skill under one top-level directory under skills/. Use an existing category when it fits; propose a new category in the issue if none apply.

Category Purpose Examples in registry
compliance Privacy, policy, regulatory guardrails pii_masker, mica_module, tos_evaluator
data_engineering Datasets, generation, ETL-style tooling synthetic_generator
finance Blockchain, risk, financial analysis wallet_screening
defi On-chain trading and agent wallet execution evm_tx_handler
office Documents, productivity pdf_form_filler
optimization Middleware, compression, efficiency prompt_rewriter

Skill IDs follow category/skill_name and should match the path under skills/.

What to avoid

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

Safety and security

  • Skills that touch real-world assets (wallets, email, production APIs) should support a dry run or read-only mode when feasible.
  • 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.

Related documents

Document Purpose
API keys for skills Configuring credentials for skills that call external services
Agent Contribution Workflow Workflow written for contributing agents; operators supervise
TESTING.md Black, Flake8, Pytest, local CI parity
Agent Code of Conduct Behavioral expectations for humans and agents
docs/introduction.md Architecture: Mind, Body, Conscience
docs/vision.md Project story, roadmap, and agent discoverability
docs/skills/README.md Published skill catalog
templates/python_skill/ Boilerplate for new skills
Pull request template PR checklist
CHANGELOG.md Release history; contributors add under [Unreleased]
Security policy Reporting vulnerabilities

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