Skip to content

Contributing

PRs welcome on EMPN-eu/empn-core. The conventions below cover the four most common contribution paths.

For the full developer-facing contracts (commit conventions, versioning, the testing pipeline), see CONTRIBUTING.md and MAINTAINERS.md at the repo root.

Register a new organisation

If your organisation isn't on the pre-prepared list (arena-ide, dezernat-zukunft, institut-avant-garde, empn), it needs to be added before you can install. One-line PR.

Pick a slug

A slug is a short, stable identifier:

  • Lowercase ASCII letters, digits, hyphens
  • Must start with a letter
  • 2–32 characters, no consecutive hyphens
  • Validation regex: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$

Valid examples: empn, dezernat-zukunft, arena-ide. Invalid: EMPN (uppercase), dezernat_zukunft (underscore), -empn (leading hyphen).

Open the PR

Two changes:

  1. Add a row to plugins/empn-core/shared/_orgs.yaml: 
    - slug: <your-slug>
  display_name: <Your Organisation Full Name>
  contact: <primary contact email>
  overlay_dir: <your-slug>
  joined: <YYYY-MM-DD>
  2. Create plugins/empn-core/shared/<your-slug>/ with at least a README.md (you can copy shared/arena-ide/README.md as a template).

Maintainer reviews that the slug is unique, the folder exists, and the row is well-formed. Merge cycle is short.

If you don't write code, email the maintainer with your slug, your organisation's full name, and a contact email. They open the PR for you.

Suggest improvements to shared docs

Three buckets:

  • Universal rules (source-tier additions, EU process clarifications, anti-AI-tone patterns, file-format constraints) → edit _common/<doc>.md. PR review checks the change applies network-wide.
  • EMPN identity (house style, themes, narrative arc, presentation conventions) → edit empn/<doc>.md. Only EMPN maintainers merge changes here.
  • Your own overlay → edit <your-slug>/<doc>.md. Maintainer reviews the change doesn't leak into other installs.

Author a new skill

Skills are markdown files under plugins/empn-core/skills/<name>/SKILL.md. The fastest path is to run skill-builder in any Cowork conversation — it walks you through the SKILL.md frontmatter, the trigger phrases, the hand-offs, and files a PR via the GitHub MCP.

Manually, the contract is:

  • Frontmatter with name, description (containing 2–4 quoted trigger phrases that route users to the skill).
  • Body under ~100 lines. Third person. Structure: what it does → how to run it → output format → hand-offs to other skills.
  • No org-specific behaviour. A skill that only works for one organisation isn't a skill — it's a script. Move org-specific logic into shared/scripts/<name>.py keyed off EMPN_ORG.
  • Source-tier lists link to the shared doc (shared/_common/themes/<theme>/data-tiers.md or similar), never inline.

See shared/_common/skill-authoring-guide.md for the full authoring conventions.

Report a bug or suggest an idea

Two skills do this for you, no Git knowledge required:

  • skill-feedback — for "this skill misbehaves" or "this output is wrong". Captures context and files a GitHub issue.
  • skill-idea — for "I'd like a skill that does X". Logs the idea even if you don't have a full design.

Both work in any Cowork conversation. If the GitHub MCP isn't connected on your install, they print a paste-ready issue block instead.

PR checklist

Before merging:

  1. Local plugin validation passes: claude plugin validate .
  2. Affected skills are triggered against the prompts in their description field — outputs are sensible.
  3. Version bumped in plugins/empn-core/.claude-plugin/plugin.json in the same commit. Semver: patch = wording, minor = new skill, major = removal or rename.
  4. If shared/ changed, the repo-audit consistency check passes — run it locally or wait for the scheduled CI agent.