dan/skills
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
skills/docs/intent/2026-01-25-skill-organization.md
dan 9ce4c83a17 feat(skills): consolidate skill organization across agents 
- Add piSkills option to ai-skills module for pi-only skills
- Add ralph-work-loop skill (depends on pi extension)
- Update skills.nix registry with nix-review, ralph-work-loop, ui-query
- Add intent/approach/work docs for skill organization effort

Universal skills deploy to claude/codex/opencode/gemini.
Pi-only skills (ralph-work-loop) deploy to ~/.pi/agent/skills/ only.
2026-01-25 11:49:29 -08:00

2.1 KiB
Raw Blame History

Intent: Skill Organization Across Agents

Motivation

Skills are scattered across multiple directories (~/.codex/skills/, ~/.claude/skills/, ~/.pi/agent/skills/), leading to duplication and drift. Some repos load skills they don't need. We want a single source of truth with clean deployment to all agents.

Need

A maintainable system for:

  1. Developing skills in one place
  2. Deploying to all agent locations (pi, Claude Code, OpenCode, Codex)
  3. Filtering which skills load in which repos
  4. Keeping compatibility with agents we might use later

Use-Cases

  • Skill development: Edit a skill in ~/proj/skills/, run deploy, all agents pick it up after Nix rebuild.
  • Per-repo filtering: Working in a Python project — don't load nix-review. Working in a Nix project — don't load python-lint.
  • Agent compatibility: Switch to Claude Code for a session — same skills available, same behavior.
  • Avoiding drift: Fix a bug in worklog skill — fix it once, deployed everywhere. No stale copies in random directories.

Success Criteria

  • Single source of truth for global skills (in dotfiles, managed by Nix)
  • All agents (pi, Claude Code, OpenCode, Codex) load skills from their expected locations
  • Per-repo skill filtering works (via pi settings or project config)
  • No duplicate skill directories to maintain
  • Development workflow: edit in skills repo → deploy → Nix rebuild → available everywhere

Constraints

  • Must work with Nix/home-manager deployment (no direnv, no runtime symlink management)
  • Skills must remain compatible with Agent Skills standard (SKILL.md format)
  • Pi is primary agent, but others must keep working
  • Extensions (TypeScript) are pi-only, separate concern for now

Anti-Goals

  • Not changing skill format: Skills stay as SKILL.md + scripts, no new abstraction
  • Not building a skill manager tool: Use Nix for deployment, not a custom CLI
  • Not per-file filtering: Filtering is per-skill, not per-file within a skill
  • Not solving extension organization: Extensions stay in ~/.pi/agent/extensions/, address later if needed