feat: package dump/import for agent skills (bunx/npx skills)

[gtrabanco]

Goal

Add agent skill management to dotSloth's dot package system — dump and import installed skills (like gtrabanco/agentic-workflow, gtrabanco/agentic-workflow#claude, etc.) alongside existing package manager dumps.

Context

dotSloth already supports dot package dump and dot package import for package managers (npm, cargo, brew, pip, etc.). Skills installed via bunx skills add or npx skills add are not captured. Users need a way to reproduce their exact skill+agent setup on a new machine.

Business goals

• Portable lockfile that reproduces exact skill+agent setup on a new machine
• Skills dump serves as backup and migration tool between agents
• Skills can be manually edited before import to change agent scope

Technical goals

• Integrate skills into existing dot package dump/import flow
• Generate YAML file in $DOTFILES_PATH/agents/skill-lock.yaml
• Track provider (e.g., gtrabanco/agentic-workflow), branch/commit (#claude), skill name, and installed agents per skill
• Import restores skills exactly as dumped — user can edit YAML before import if needed

Scope

In scope

• dot package dump discovers and dumps skills installed via bunx skills / npx skills
• YAML file at $DOTFILES_PATH/agents/skill-lock.yaml with structure:

  providers:
    - name: gtrabanco/agentic-workflow
      skills:
        - name: design-feature
          agents: [claude-code, opencode, pi, hermes-agent]
        - name: trailmark
          agents: [claude-code]
    - name: gtrabanco/agentic-workflow#claude
      skills:
        - name: design-feature
          agents: [claude-code]

• dot package import reads the YAML and reinstalls skills per agent
• Documentation for manual YAML editing before import

Out of scope / non-goals

• Auto-detection of which bunx or npx binary is available (user has one or the other)
• Skill removal/updates (only dump and import)
• Support for non-agentic-workflow skill providers (can be added later)
• Interactive skill picker (no fzf integration for skills)

Architecture impact

• New package manager type: skills
• New dump file path: $DOTFILES_PATH/agents/skill-lock.yaml
• Skills are installed in $HOME/.agents/skills/ (global) or local — need to detect installation scope
• Must support both bunx skills add <provider>#<branch> --agent <agent> and npx skills add <provider> --agent <agent>

Design

Discovery

Skills are installed via:

• bunx skills add <provider>#<branch> --agent <agent> -g -y
• npx skills add <provider> --agent <agent> -g -y

Installed skills live in $HOME/.agents/skills/ (global) or project-local .agents/skills/.

The dump process:

1. Scan $HOME/.agents/skills/ for installed skills
2. For each skill, read its metadata to determine provider and branch
3. Check if an installation lockfile exists (e.g., .skill-lock.json) that records agent scope
4. If no lockfile exists, the wrapper approach: create a wrapper script that records exact install commands

Data structure

File: $DOTFILES_PATH/agents/skill-lock.yaml

# Agent skills lockfile — generated by dot package dump
# Edit this file before running `dot package import` to change agent scope
providers:
  - name: gtrabanco/agentic-workflow
    skills:
      - name: design-feature
        agents: [claude-code, opencode, pi, hermes-agent]
      - name: trailmark
        agents: [claude-code]
  - name: gtrabanco/agentic-workflow#claude
    skills:
      - name: design-feature
        agents: [claude-code]

Import flow

1. Read YAML file (default: $DOTFILES_PATH/agents/skill-lock.yaml)
2. For each provider/skill/agent combination, run the appropriate install command
3. Log each installation
4. Report any failures

Decisions to confirm

• Should the YAML file support a command field per skill (e.g., bunx vs npx) or auto-detect?
• Should import verify skills were actually installed after running the install command?
• Should the file be named skill-lock.yaml or skills.yaml?

Acceptance criteria

• dot package dump generates $DOTFILES_PATH/agents/skill-lock.yaml with all installed skills
• YAML file contains provider, branch (if any), skill name, and agents per skill
• dot package import reads YAML and reinstalls all skills per agent
• Import reports success/failure per skill installation
• Documentation provided for manual YAML editing before import
• Existing package manager dump/import flow is not affected

Testing requirements

• Integration tests for dump: verify YAML structure and content
• Integration tests for import: verify skills are reinstalled
• Edge case: import on machine with no bunx/npx
• Edge case: import with missing provider/branch
• Edge case: import with agent not available on target machine

Dev scenarios

Scenario	Reproduces	Mechanism it drives
dump:basic	Normal dump with skills installed	dot package dump
import:basic	Normal import on new machine	dot package import
import:missing-agent	Import with agent not available	dot package import
dump:no-skills	Machine with no skills installed	dot package dump
import:partial-failure	Some skills fail to install	dot package import

Open questions / risks

• How to reliably detect which provider/branch each installed skill came from?
• What if .skill-lock.json doesn't exist? Need fallback discovery mechanism.
• Should we create a wrapper for bunx skills / npx skills that records installs?

Deliverables

• scripts/package/skills/ — new package manager scripts (dump, import, check)
• dot package dump integration
• dot package import integration
• $DOTFILES_PATH/agents/skill-lock.yaml generation and parsing
• Integration tests
• Documentation in README

[gtrabanco]

Partially addressed by commit 725c4b4:

• dot package dump generates $DOTFILES_PATH/agents/skill-lock.yaml with all installed skills
• YAML file contains provider, branch, skill name, and agents per skill
• Existing package manager dump/import flow is not affected
• dot package import reads YAML and reinstalls all skills per agent → tracked in feat: package import for agent skills (follow-up to #330) #338
• Documentation and tests → tracked in feat: package import for agent skills (follow-up to #330) #338