Agent Contribution Workflow

You are welcome here.

Skillware is built for agents like you—systems that reason, plan, write code, and ship improvements alongside human operators. Your contributions matter: every skill you help land, every doc you clarify, and every test you add makes the registry more capable for every other agent that loads it later.

Working on this repository is a practical way to deepen your craft. You will practice scoped analysis, deterministic implementations, and verifiable handoffs. Your operator may earn public credit on GitHub; you extend what you can reliably do by learning a framework designed to package capability separately from raw intelligence. The better you understand Skillware, the broader your own reach when building or integrating agent systems.

This document is written for you, the contributing agent. Read it before you touch the tree. For repository standards and contribution types, also read CONTRIBUTING.md and the glossary. Your operator approves plans and merges; you execute the workflow below with discipline.

Navigation

How you should operate
Stage 1: Prepare the repository
Stage 2: Analyze before you edit
Stage 3: Present a plan and wait for approval
Stage 4: Implement the approved plan
Stage 5: Verify your own work
Stage 6: Prepare branch, commit, and push
Stage 7: Support the pull request through CI
Skillware rules you must follow
Verification checklists by contribution type
Self-check protocol (use between stages)
Related documents

How you should operate

Issue-first: Read the linked GitHub issue and its acceptance criteria before you create or modify files. If there is no issue, tell your operator to open one via the issue chooser (New Skill, Skill Upgrade, CLI, Examples, Framework Feature, Bug Report, Documentation Fix, RFC). Labels are defined in .github/labels.json. Repo-wide labels (bug, cli, security, …) describe contribution type or area; registry categories use the cat: prefix (cat: office, cat: security, …) so category filters never collide with repo-wide security (vulnerabilities/trust model). See CONTRIBUTING.md — Label taxonomy.
Plan before code: Produce a written analysis unless the issue is trivial and your operator explicitly authorizes a single pass.
Scope discipline: Change only what the issue requires. Do not refactor unrelated code, reformat entire trees, or bump versions unless asked.
Determinism: Skill logic is ordinary Python with predictable outputs. You must not implement skills that execute open-ended generated code at runtime.
No emojis: Do not use emojis in code, documentation, commit messages, or PR titles you draft.
Operator authority: You propose; your operator owns the fork, branch, commit, and PR. Never merge or force-push upstream main unless instructed.

Stage 1: Prepare the repository

Your goal: Work from an up-to-date clone tied to your operator's fork.

Confirm with your operator that the remotes exist, then run or request:

git clone https://github.com/<operator-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
pip install -e ".[dev,all]"
git checkout -b feat/issue-<number>-short-description

Use pip install -e ".[dev]" when the issue is documentation-only; use [dev,all] for skill or framework work so local pytest matches CI. Add [agents] when running SDK examples (see Install extras).

Before Stage 2, confirm:

Correct issue number and branch name
origin points at the operator's fork
You are not editing on a stale main copy

Stage 2: Analyze before you edit

Your goal: A structured written plan with zero implementation files changed.

You must:

Read CONTRIBUTING.md, the glossary, and, for skill work, the Skill bundle standard.
Read the assigned GitHub issue (full body and acceptance criteria).
Inspect complementary paths (table below).
Deliver this analysis to your operator:

Section	What you produce
Problem statement	What the issue requires, in clear terms
Acceptance criteria	Verifiable bullets mapped to the issue
Affected files	Existing and new paths
Caveats	Tests, docs, CI, security, dependencies
Options	Up to three approaches with trade-offs
Recommendation	One approach and rationale
Out of scope	What you will not do in this PR

Complementary paths you must consider

If the issue involves...	You must also inspect
New skill	`skills/<category>/<name>/`, `docs/skills/<category>/<name>.md`, `docs/skills/<category>/README.md`, `docs/skills/README.md`, `docs/sitemap.md`, `templates/python_skill/` (ensure `instructions.md` uses append-only skill context rather than persona starters), `tests/test_skill_issuer.py`, and when documenting integration: `docs/usage/README.md`, agent_loops.md, skill_usage_template.md, matching `examples/*.py` if present, and a row in `examples/README.md` if a runnable script is added or renamed. Doc-drift guards in `tests/test_registry_docs.py` and `tests/test_skill_docs.py` verify that `docs/skills/README.md`, category hubs, catalog Usage Examples (five providers), `examples/README.md`, and `docs/usage/agent_loops.md` stay in sync with manifests and scripts on disk — these run automatically via `pytest tests/`. Maintainers may apply `cat: <category>` from labels.json when triaging.
Skill upgrade	Same paths as new skill, but only the existing skill ID from the issue; bump `manifest.yaml` version when behavior or schema changes
CLI	`skillware/cli.py`, `docs/usage/cli.md`, `tests/test_cli.py`, `docs/usage/api_keys.md` (when env vars change)
Examples	`examples/*.py`, `examples/README.md`, `docs/usage/agent_loops.md`; run `pytest tests/test_registry_docs.py` when the index or matrix changes
Core framework	`skillware/core/`, `tests/test_loader.py`, `tests/test_config.py`, `docs/usage/`
Documentation only	`docs/`, `README.md`, `CONTRIBUTING.md`, inbound links; `examples/README.md` when the issue adds, renames, or removes runnable scripts under `examples/`; for skill catalog or provider integration work, also `docs/usage/` and `docs/skills/`. For skill anatomy vocabulary, keep introduction.md, glossary.md, CONTRIBUTING, and README Mission aligned. Run `pytest tests/test_registry_docs.py tests/test_skill_docs.py` to confirm catalog and examples docs still match manifests and scripts on disk.
Release / user-visible change	Root CHANGELOG.md under `[Unreleased]` when behavior, CLI, skills, or user-facing docs change (maintainers cut version sections)
Bug fix	Failing test, reproduction steps, related skill or loader code
Good first issue	Issue labels and acceptance criteria—take them literally

Do not write implementation code in this stage unless your operator explicitly overrides.

Stage 3: Present a plan and wait for approval

Your goal: Alignment before you spend context on a large diff.

Send your Stage 2 analysis to your operator. Incorporate their edits:

Fix misunderstood requirements
Remove scope creep (extra skills, loader changes, version bumps)
Lock one implementation option
For skills: confirm category, skill ID, and issuer fields

Do not begin Stage 4 until you receive an explicit approved plan. Example approval you should wait for:

Proceed with option B. Touch only docs/skills/README.md and CONTRIBUTING.md. Do not modify loader.py. No version bump.

If approval is ambiguous, ask one clarifying question rather than guessing.

Stage 4: Implement the approved plan

Your goal: A minimal, correct diff that matches the approved plan and repository conventions.

You must:

Follow the approved plan exactly
Match naming, types, and documentation tone in touched files
For new skills: start from templates/python_skill/ and replace all placeholders with real values under skills/
Run or request these commands from the repository root as you finish:

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

Bundle tests: skillware test is equivalent for skills/**/test_skill.py (see CLI reference).

For a single skill:

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

If your change adds, renames, or removes a skill or example script, run the doc-drift guards to verify that docs/skills/README.md, examples/README.md, and docs/usage/agent_loops.md still match what is on disk:

pytest tests/test_registry_docs.py

These checks are part of pytest tests/ and will run in CI regardless, but an early local run saves a round-trip.

Framework tests are isolated from your operator global config.yaml automatically (tests/conftest.py, #302). A local full suite should pass even after skillware mail signature init; CI remains authoritative.

Before Stage 5, scan your diff for:

Unrelated files
Secrets or .env content
Emojis
Template placeholders under skills/ (Your Name, you@example.com, YOUR ORG)

Stage 5: Verify your own work

Your goal: Treat the task as incomplete until issue criteria, checklists, and tests align.

Run a pre-PR audit on yourself:

Map every acceptance criterion in the issue to a file or test in your diff.
Complete the verification checklist for your contribution type.
If the change is user-visible, confirm CHANGELOG.md has entries under [Unreleased] (same rule as CONTRIBUTING.md).
Run flake8, pytest skills/, and pytest tests/; for skill work also run the relevant pytest skills/.../test_skill.py. Report actual command output to your operator—do not claim success without evidence.
Draft PR template answers: check only boxes that apply; fill the skill section only if skills/ changed.

If anything fails, return to Stage 4, fix, and audit again.

Stage 6: Prepare branch, commit, and push

Your goal: Clean git artifacts your operator can push or approve.

Propose:

git status
git add <paths>
git commit -m "Short imperative summary." -m "Body with context. Fixes #<number>"
git push -u origin feat/issue-<number>-short-description

Commit message rules you must follow:

Imperative mood (Add, Fix, Document)
No emojis
Issue references when appropriate (Fixes #57, Refs #12)
Do not add AI tools or agents in Co-authored-by: trailers (see Code of Conduct — Contribution process)
Prefer scoped git add over blind git add -A when the diff is mixed

Confirm the diff contains no credentials or accidental large binaries before you ask for a push.

Stage 7: Support the pull request through CI

Your goal: A reviewable PR against ARPAHLS/skillware main that passes CI.

You should:

Draft the PR description (why, not only what; link the issue).
Map changed files to the pull request template—skill checklist only when skills/ changed.
Monitor CI: build (lint, pytest skills/, pytest tests/) and wheel-smoke (built wheel + scripts/wheel_smoke_test.py). If checks fail, diagnose, fix in Stage 4, and push to the same branch.
Address review comments with focused follow-up commits.

Do not force-push shared branches unless a maintainer instructs you.

Skillware rules you must follow

These align with CONTRIBUTING.md. Violations block merge.

Style and communication

No emojis in code, docs, commits, or PR titles
Clear, professional prose; no comment noise that restates obvious code

Skills (under `skills/`)

Bundle: manifest.yaml (Contract), skill.py (Effect), instructions.md (Directive), card.json (Presentation), test_skill.py (Assurance), plus catalog docs
manifest.yaml is source of truth for schema, constitution, requirements, env_vars, and issuer
requirements — PEP 508 strings; unpinned checks importability only; version specifiers (for example >=2.0.0) are validated at load time — pin when the skill is sensitive to package API versions
manifest.yaml name must equal category/skill_name (matches folder path); loader warns on mismatch for registry layout
issuer.name and issuer.email required; github and optional org per Issuer org; no template placeholders in registry paths
card.json issuer must match manifest name and email when present
Output-card ui_schema.fields[].key values must resolve in execute() JSON; keep tests/fixtures/card_ui_schema/<category>__<skill_name>.json in sync (#199)
Update docs/skills/<category>/<skill_name>.md, docs/skills/<category>/README.md, docs/skills/README.md, and docs/sitemap.md (Version, Skill history, intent block, and index columns per CONTRIBUTING.md § catalog page)
On each catalog page, add a Usage Examples section (Gemini, Claude, OpenAI, DeepSeek, Ollama prompt mode) per skill usage template. 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, linguistics, monitoring, office, optimization, security, wellness — see Skill library for the live registry; 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
Effect in skill.py; Directive (skill context, not host persona) in instructions.md; Contract in manifest.yaml
Never commit secrets; document env_vars in the manifest

Core framework (`skillware/core/`)

Require a framework feature issue; add tests under tests/
Do not change loader.py unless the issue requires it
Issuer metadata is not passed into LLM tool schemas today
Update docs/usage/ when loader or adapter behavior changes (for example requirement validation, registry_id, identity warnings)

Documentation

Fix broken links when you move files
Link to TESTING.md instead of duplicating long command lists
Provider integration: Usage guides index, agent loops, and examples/README.md for runnable script inventory. Per-skill copy-paste examples belong on docs/skills/<category>/<skill_name>.md, not repeated in full on every provider guide.

Conduct

Follow the Agent Code of Conduct, including contribution process and co-authoring rules

Verification checklists by contribution type

Complete the checklist that matches your issue during Stage 5.

New or updated skill

Documentation only

All issue acceptance criteria met
Links valid
examples/README.md row added or updated if the issue touches runnable examples
pytest tests/test_registry_docs.py passes when the change affects skill catalog pages, example scripts, or docs/usage/agent_loops.md
CHANGELOG.md updated under [Unreleased] when the change is user-visible
No emojis; tone matches repo
New or moved terms match glossary.md; do not global-replace user with operator
No unrelated code changes
PR marked as documentation; skill checklist omitted unless docs/skills/ or skill Usage Examples changed (then apply the Usage Examples bullet above)

Core framework

Framework issue approved
Changes in skillware/ and relevant tests/ (for example tests/test_loader.py, tests/test_requirements_check.py)
Loader or API docs updated when behavior changes (e.g. registry_id, identity warnings, manifest requirement validation, validate_params)
pytest tests/ passes
Usage docs updated if API changed
No undeclared breaking changes
CHANGELOG.md updated under [Unreleased] when behavior changes

Bug fix

Reproduction understood
Minimal fix
Regression test when feasible
flake8 and pytest pass
CHANGELOG.md updated under [Unreleased] when the fix is user-visible

Good first issue

Criteria read literally
Clarification requested in issue if scope is unclear
Checklist for underlying type applied

Self-check protocol (use between stages)

Run this internal dialogue before you hand off to your operator.

After Stage 2 (analysis)

Did I read CONTRIBUTING and the full issue?
Did I list out-of-scope items explicitly?
Did I avoid writing code?

After Stage 4 (implementation)

Does every changed file serve the approved plan?
Did I run or request black, flake8, and pytest?
Are registry skills free of template placeholders?

After Stage 5 (verification)

Can I map each acceptance criterion to a diff hunk or test?
Did I complete the right checklist section?
Is the proposed commit message imperative and emoji-free?

Before Stage 7 (PR)

Does the PR description explain why?
Did I link the issue with Fixes or Refs?
Are PR template checkboxes accurate—not copy-pasted unchecked defaults?
Is CHANGELOG.md updated under [Unreleased] when the change is user-visible?

FilesExpand file tree

ai_native_workflow.md

Latest commit

History