Skip to content

plugin: expand python-skills workflows#53

Open
gaelic-ghost wants to merge 6 commits into
mainfrom
python-skills/gap-analysis
Open

plugin: expand python-skills workflows#53
gaelic-ghost wants to merge 6 commits into
mainfrom
python-skills/gap-analysis

Conversation

@gaelic-ghost
Copy link
Copy Markdown
Owner

@gaelic-ghost gaelic-ghost commented May 15, 2026

Summary

  • repair python-skills child validation after the child README collapse
  • add Python project shape, implementation, diagnostics, package, tooling, CI, and upgrade workflow skills
  • prepare the shared Socket 6.10.0 release version surfaces

Verification

  • uv run scripts/validate_repo_metadata.py from plugins/python-skills
  • uv run pytest from plugins/python-skills
  • uv run ruff check . from plugins/python-skills
  • uv run mypy . from plugins/python-skills
  • uv run scripts/validate_socket_metadata.py
  • temporary CODEX_HOME Socket marketplace smoke test

Summary by CodeRabbit

  • New Features

    • Added seven new Python workflow skills: build, choose project shape, diagnose, CI, package validation, tooling/style alignment, and upgrades.
    • Expanded Python-skills plugin descriptions and default prompts to cover broader Python workflows.
  • Chores

    • Bumped platform/plugin versions from 6.9.0 → 6.10.0.
    • Reclassified the Python-skills plugin category to Developer Tools.
    • Added Milestone 7 to the roadmap.
  • Documentation

    • Added maintainer plan and extensive architecture/backlog updates for Python-skills.
  • Tests

    • Updated plugin smoke tests and validation to reference agent guidance.

Review Change Stack

@gaelic-ghost gaelic-ghost added the enhancement New feature or request label May 15, 2026
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 15, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2b765e41-46b1-42ba-8f6c-6d7e97706dc7

📥 Commits

Reviewing files that changed from the base of the PR and between 9c1c4d1 and b00d35b.

📒 Files selected for processing (8)
  • README.md
  • docs/architecture/architecture.json
  • plugins/productivity-skills/skills/maintain-project-architecture/references/architecture-json.md
  • plugins/productivity-skills/skills/maintain-project-architecture/scripts/maintain_project_architecture.py
  • plugins/productivity-skills/skills/maintain-project-architecture/tests/test_maintain_project_architecture.py
  • plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml
  • plugins/python-skills/skills/python-upgrade-workflow/SKILL.md
  • plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml
✅ Files skipped from review due to trivial changes (1)
  • plugins/productivity-skills/skills/maintain-project-architecture/references/architecture-json.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml

📝 Walkthrough

Walkthrough

This PR expands the python-skills plugin with seven new skill workflows, refactors its validator to require AGENTS.md guidance, updates architecture/manifest/catalog documentation (including marketplace category), and synchronizes version 6.10.0 across the root package and plugin manifests.

Changes

Python Skills Plugin Expansion

Layer / File(s) Summary
Planning, roadmap, and scope definition
ROADMAP.md, TODO.md, docs/maintainers/python-skills-plugin-plan.md, .agents/plugins/marketplace.json, README.md
Adds Milestone 7 to ROADMAP; records completed TODO items; introduces maintainer plan and updates marketplace/README catalog text (python-skills reclassified to "Developer Tools").
Validator refactoring: README to AGENTS.md
plugins/python-skills/scripts/validate_repo_metadata.py
Removes README-based checks and adds validate_child_guidance() to verify AGENTS.md contains required guidance snippets; run() updated to call the new validator.
New Python skill definitions: core workflows
plugins/python-skills/skills/build-python-project/SKILL.md, plugins/python-skills/skills/choose-python-project-shape/SKILL.md, plugins/python-skills/skills/diagnose-python-project/SKILL.md, plus their agents/openai.yaml files
Adds three foundational skills with SKILL.md guidance and agent interface configs (display names, prompts, brand colors, allow implicit invocation).
New Python skill definitions: CI and package workflows
plugins/python-skills/skills/python-ci-workflow/*, python-package-workflow/*, python-tooling-style-workflow/*, python-upgrade-workflow/*
Adds four workflow skills covering CI authoring, package validation, tooling/style alignment, and upgrade workflows with SKILL.md guidance and agent YAMLs.
Python-skills plugin manifest and test updates
plugins/python-skills/.codex-plugin/plugin.json, plugins/python-skills/pyproject.toml, plugins/python-skills/tests/test_plugin_smoke.py
Bumps plugin version to 6.10.0; updates description, homepage/repository URLs, interface text/default prompt; test updated to assert AGENTS.md surface and that root README.md is absent.
Architecture documentation updates
docs/architecture/ARCHITECTURE.md, docs/architecture/architecture.json
Adds evidence, targets, and relationships for new Apple/Dotnet/Python skills; populates dotnet-skills targets; updates detectedAt and projectRoot fields.
projectRoot normalization & tests
plugins/productivity-skills/skills/maintain-project-architecture/...
Changes generated projectRoot to "." in script and reference docs and updates tests to assert the normalized projectRoot.
Coordinated version bump: 6.9.0 → 6.10.0
pyproject.toml, multiple plugins/*/.codex-plugin/plugin.json and pyproject.toml files
Synchronizes package and plugin versions to 6.10.0 across root and many plugins for release coordination.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

Suggested labels

documentation

Poem

🐰 I hopped through docs and updated the plan,
Seven Python skills sprang up in my hand.
AGENTS now guide where READMEs once stood,
Versions aligned — six point one oh, good!
A rabbit's small shuffle, tidy and neat —
Docs, tests, and skills now ready to meet.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'plugin: expand python-skills workflows' directly and clearly describes the main change: the expansion of Python skills workflows. It is specific, concise, and accurately represents the primary objective of this PR.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch python-skills/gap-analysis

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture/architecture.json`:
- Line 501: The projectRoot field currently contains a machine-local absolute
path; replace the value of the "projectRoot" key in
docs/architecture/architecture.json with a repository-relative path (for example
"." or the repo subpath like "socket-wt-python-skills-gap-analysis") so the file
no longer contains workstation-specific absolute paths; also update any code
that generates this JSON to emit a repo-relative value instead of an absolute
filesystem path.

In `@plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml`:
- Line 3: The short_description value contains the term "package" twice; update
the short_description key to remove the duplicated word so the sentence reads
cleanly (e.g., "Choose Python package, service, MCP, workspace, test, tooling,
CI, or upgrade shape.") — edit the short_description string in the YAML
(short_description) to remove the duplicate and ensure punctuation/commas remain
correct.

In `@plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml`:
- Line 5: The agent default prompt (the default_prompt value) is missing the
SKILL guardrail that forbids publishing/creating releases unless explicitly
requested; update the default_prompt string to mirror the SKILL.md constraint
exactly by appending a clear instruction such as “do not publish or create
releases unless explicitly requested” (or the exact wording used in SKILL.md) so
the agents/openai.yaml default_prompt and the SKILL.md contract remain
consistent.

In `@plugins/python-skills/skills/python-upgrade-workflow/SKILL.md`:
- Around line 45-49: The grep inventory step currently hard-codes optional paths
(the first rg that searches "requires-python|dependencies|..." and the second rg
--files -g list) which can fail if docs/README.md/.github are absent; update
SKILL.md so the first rg runs repository-wide (remove explicit optional paths
from the file list) or gate those paths with existence checks, or change the
second command to glob only required files (e.g., keep -g 'pyproject.toml' -g
'uv.lock' -g '.python-version' -g '.github/workflows/*.yml' -g
'.github/workflows/*.yaml') and omit docs/README.md, ensuring the workflow step
won’t error when optional paths are missing.

In `@README.md`:
- Line 81: The `python-skills` catalog bullet is too implementation-heavy;
replace its long technical list with a brief, user-facing installation/usage
line for `python-skills` (e.g., "Python runtime and tooling for running
Python-based skills; see docs for setup"), and add a link to a deeper docs page
for development details (point readers to a dedicated docs/CONTRIBUTING or
workflow page) so the root README stays short and nontechnical.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5acd802d-75a3-47b3-864a-234ca6f2daef

📥 Commits

Reviewing files that changed from the base of the PR and between 2c9e434 and 9c1c4d1.

⛔ Files ignored due to path filters (8)
  • plugins/agent-plugin-skills/uv.lock is excluded by !**/*.lock
  • plugins/apple-dev-skills/uv.lock is excluded by !**/*.lock
  • plugins/cardhop-app/mcp/uv.lock is excluded by !**/*.lock
  • plugins/productivity-skills/uv.lock is excluded by !**/*.lock
  • plugins/python-skills/uv.lock is excluded by !**/*.lock
  • plugins/things-app/mcp/uv.lock is excluded by !**/*.lock
  • plugins/things-app/uv.lock is excluded by !**/*.lock
  • uv.lock is excluded by !**/*.lock
📒 Files selected for processing (42)
  • .agents/plugins/marketplace.json
  • README.md
  • ROADMAP.md
  • TODO.md
  • docs/architecture/ARCHITECTURE.md
  • docs/architecture/architecture.json
  • docs/maintainers/python-skills-plugin-plan.md
  • plugins/agent-plugin-skills/.codex-plugin/plugin.json
  • plugins/agent-plugin-skills/pyproject.toml
  • plugins/apple-dev-skills/.codex-plugin/plugin.json
  • plugins/apple-dev-skills/pyproject.toml
  • plugins/cardhop-app/.codex-plugin/plugin.json
  • plugins/cardhop-app/mcp/pyproject.toml
  • plugins/dotnet-skills/.codex-plugin/plugin.json
  • plugins/productivity-skills/.codex-plugin/plugin.json
  • plugins/productivity-skills/pyproject.toml
  • plugins/python-skills/.codex-plugin/plugin.json
  • plugins/python-skills/pyproject.toml
  • plugins/python-skills/scripts/validate_repo_metadata.py
  • plugins/python-skills/skills/build-python-project/SKILL.md
  • plugins/python-skills/skills/build-python-project/agents/openai.yaml
  • plugins/python-skills/skills/choose-python-project-shape/SKILL.md
  • plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml
  • plugins/python-skills/skills/diagnose-python-project/SKILL.md
  • plugins/python-skills/skills/diagnose-python-project/agents/openai.yaml
  • plugins/python-skills/skills/python-ci-workflow/SKILL.md
  • plugins/python-skills/skills/python-ci-workflow/agents/openai.yaml
  • plugins/python-skills/skills/python-package-workflow/SKILL.md
  • plugins/python-skills/skills/python-package-workflow/agents/openai.yaml
  • plugins/python-skills/skills/python-tooling-style-workflow/SKILL.md
  • plugins/python-skills/skills/python-tooling-style-workflow/agents/openai.yaml
  • plugins/python-skills/skills/python-upgrade-workflow/SKILL.md
  • plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml
  • plugins/python-skills/tests/test_plugin_smoke.py
  • plugins/rust-skills/.codex-plugin/plugin.json
  • plugins/spotify/.codex-plugin/plugin.json
  • plugins/swiftasb-skills/.codex-plugin/plugin.json
  • plugins/things-app/.codex-plugin/plugin.json
  • plugins/things-app/mcp/pyproject.toml
  • plugins/things-app/pyproject.toml
  • plugins/web-dev-skills/.codex-plugin/plugin.json
  • pyproject.toml

Comment thread docs/architecture/architecture.json Outdated
Comment thread plugins/python-skills/skills/choose-python-project-shape/agents/openai.yaml Outdated
Comment thread plugins/python-skills/skills/python-upgrade-workflow/agents/openai.yaml Outdated
Comment thread plugins/python-skills/skills/python-upgrade-workflow/SKILL.md
Comment thread README.md Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant