Skip to content

Ship core skills as package data for self-documenting projio installations

Problem

When another lab installs projio via pip install projio, they get CLI tools and MCP server but no workflow guidance. The skills layer (skill_read(), agent_instructions()) only works when the project has .projio/skills/ populated — which requires cloning the projio repo or manually copying skills.

The projio docs website may not be publicly accessible, and new users shouldn't need to clone the projio source repo just to learn how to use the tool.

Proposed solution

Ship a core set of skills as package data in src/projio/data/skills/. When skill_read(name) is called:

  1. Check project-local .projio/skills/{name}/SKILL.md (current behavior)
  2. Fallback to projio/data/skills/{name}/SKILL.md (bundled with package)

This means any projio installation becomes self-documenting for agents. The agent gets full workflow guidance without the user needing to set up anything beyond pip install.

Which skills to bundle

Ship skills that describe projio-native workflows — not lab-specific or project-specific ones:

  • pipeio-guide — pipeline authoring reference
  • figio-guide — figure orchestration
  • biblio-batch-curate — bibliography workflows
  • literature-discovery — paper discovery
  • questio-* — research question workflows
  • rag-query — semantic search
  • idea-capture, issue-triage, issue-fix — note workflows

Lab-specific skills (e.g., sirota lab conventions) stay in the projio repo's docs/prompts/skills/ and get copied to projects via projio sync or profile setup.

What NOT to do

  • Don't ship the full docs site as package data — maintenance burden, goes stale
  • Don't build a projio guide CLI — the agent is the primary interface, skill_read() already works
  • Don't duplicate content between package skills and the docs site — the skills ARE the canonical source, the docs site can render them

Implementation scope

  1. Copy selected skills to src/projio/data/skills/
  2. Update skill_read() in mcp/context.py to add the package-data fallback
  3. Update agent_instructions() to mention bundled skills when no project skills exist
  4. Add to pyproject.toml package-data includes