Skip to content

Packaging: ship the skill catalog as package data in the pipefy wheel #699

Closed

Description

@mocha06

Problem

No published artifact contains the skills:

  • The SDK wheel packages only src/pipefy_sdk, with no include or force-include (packages/sdk/pyproject.toml). The mcp and cli wheels do the same.
  • The GitHub Release attaches only dist/*.whl (.github/workflows/release.yml).
  • Skills reach users only through skills.sh (it reads the repo directly), the Cursor plugin manifest, or git clone.

A Python consumer therefore cannot pin a skill version. It also cannot guarantee that the skills it loads name methods that exist in the pipefy version it installed.

Proposal

  • Ship the skill catalog as package data in the pipefy (SDK) wheel, flattened to <skill-name>/SKILL.md plus any references/ files. Many agent frameworks load skills in this one-level layout.
  • Add a small accessor, for example pipefy_sdk.skills.directory() -> pathlib.Path, so consumers do not hard-code the location inside the package.
  • Honor the surfaces field from the frontmatter issue in this milestone. Either ship only skills that apply to the SDK, or ship all of them and let the consumer filter.

With this change, the skills and the tool names that they cite always come from the same release.

Packaging detail

skills/ is at the repo root, outside the SDK package root (packages/sdk, packages = ["src/pipefy_sdk"]). A plain packages entry cannot reach it. The build needs a hatch force-include that maps ../../skills into pipefy_sdk/skills, or a build step that copies the files in.

release.yml builds --wheel --sdist. The sdist must carry the files too, or an install from the sdist has no skills. PyPI gets only the wheels today, but a local sdist build is still a supported path. A test should assert that the built wheel contains pipefy_sdk/skills/<name>/SKILL.md for every skill that applies to the SDK.

Non-breaking

This change only adds files to the wheel. The repo layout that skills.sh and the Cursor plugin read stays the same.

Activity

  1. added
    enhancementNew capability or intentional behavior change (not a bugfix)
    on Sep 22, 2026
  2. mocha06 commented on Sep 24, 2026

    @mocha06
    CollaboratorAuthor

    Matheus will do this one

  3. mocha06 commented on Sep 25, 2026

    @mocha06
    CollaboratorAuthor

    A build-time filter on metadata.surfaces (#698, PR #709) cannot reuse the lint parser as it stands.

    • The only parser is parse_skill_surfaces in .github/workflows/scripts/lint_skill_frontmatter.py. It needs PyYAML, which is a root dev dependency only.
    • The step that decides what goes in the wheel is a hatch build hook. uv build runs it in an isolated environment (release.yml:121 does not pass --no-build-isolation).
    • That environment has only requires = ["hatchling"] (packages/sdk/pyproject.toml:29). It cannot see PyYAML or import a file from .github/workflows/scripts/.
    • The wheel test runs in the repo and can import the lint module. It checks the result, but it does not do the filtering.

    So a build-time filter needs one of these: move the parser into packages/sdk and add PyYAML to [build-system].requires, or ship every skill and filter in the consumer. In the second case, the parser moves into pipefy_sdk.skills and PyYAML becomes a runtime dependency. Either way, one parser serves the lint and the filter, as agreed in PR #709.

  4. adriannoes commented on Sep 30, 2026

    @adriannoes
    Collaborator

    Fixed on dev by #718. Closing by hand, since Closes only fires on merge into main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew capability or intentional behavior change (not a bugfix)

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions