Skip to content

PLAN.md

Latest commit

 

History

History
532 lines (396 loc) · 15.2 KB

PLAN.md

File metadata and controls

532 lines (396 loc) · 15.2 KB

Skill CLI - Project Plan

A portable Zig CLI tool for vendoring and managing LLM skills from a central repository with per-project customization.

1) Central Skills Repository Layout

skills-repo/
  <skill-name-1>/
    SKILL.md
    (optional additional files/subdirectories)
  <skill-name-2>/
    SKILL.md
    (optional additional files/subdirectories)
  ...

Notes

  • Each skill is a directory at the root level of the repository
  • Skills must contain SKILL.md at minimum
  • Skills may contain additional files and subdirectories
  • No naming restrictions on skill names (exact match required)
  • The entire skill directory is copied during vendoring

2) Per-Project Layout After Vendoring

your-project/
  AGENTS.md                          # User's file (CLI doesn't modify)
  .config/
    skills/
      skills.json                    # Local config (JSON5 format)
  skills/
    .gitignore                       # Ignores */OVERRIDE.md
    README.md                        # Generated by CLI with LLM instructions
    <skill-name-A>/
      SKILL.md                       # Vendored copy (overwritten by updates)
      OVERRIDE.md                    # Optional, local-only, user-created
      (other vendored files...)
    <skill-name-B>/
      SKILL.md
      (other vendored files...)

skills/.gitignore

*/OVERRIDE.md

3) Configuration System

Configuration Hierarchy

  1. Local project config: .config/skills/skills.json (in project root)
  2. Global user config: ~/.config/skills/skills.json
  3. Default: git@github.com:DockYard/skills.git

Configuration Format (JSON5)

.config/skills/skills.json:

{
  "repo": "git@github.com:DockYard/skills.git"
  // "branch": "main"
  // "tag": "v1.0.0"
  // "sha": "abc123def456"
}

Rules

  • Only one of branch, tag, or sha can be specified at a time
  • If none specified, uses the repository's HEAD
  • CLI validates and errors if multiple ref types are present
  • Local config is only created when using skill init --repo or related flags
  • Global config is manually created by users to override the default

4) Override Semantics (LLM-Facing)

  • OVERRIDE.md is optional, local-only, user-created, and gitignored
  • When both SKILL.md and OVERRIDE.md exist, OVERRIDE.md takes precedence
  • The CLI generates skills/README.md with imperative instructions for LLMs
  • Agents must follow the precedence rules defined in skills/README.md

5) The skill CLI (Zig 0.15.2)

Commands

skill init [--repo <URL>] [--branch <name>] [--tag <name>] [--sha <hash>]

  • Creates skills/ directory
  • Creates skills/README.md with LLM instructions
  • Creates skills/.gitignore with */OVERRIDE.md pattern
  • If --repo or other flags provided: creates .config/skills/skills.json in project root
  • Validates that only one of --branch, --tag, or --sha is specified
  • Displays the source repo being used
  • Prints the AGENTS.md block to stdout (does not modify AGENTS.md)
  • Errors if skills/ directory already exists

skill list

  • Lists all available skill names from the remote repo
  • Fetches directly from remote (no caching) using git sparse checkout
  • Simple output: one skill name per line
  • Lists any directory under skills/ regardless of contents

skill add <name1> <name2> ...

  • Copies entire skill directories from remote repo to project
  • Does NOT automatically create OVERRIDE.md files
  • Errors and stops if any skill already exists locally
  • Notes error and continues if a skill doesn't exist in remote
  • Regenerates skills/README.md
  • Requires skills/ directory to exist (run skill init first)

skill remove <name1> <name2> ...

  • Removes skills/<name>/ directory entirely
  • If OVERRIDE.md exists, prompts for confirmation before removing that skill
  • If user declines, skips that skill and continues to next
  • Notes error and continues if skill doesn't exist locally
  • Regenerates skills/README.md

skill update [--all | <name1> <name2> ...]

  • No arguments: Lists installed skills and shows usage instructions
  • --all: Scans local skills/ directory and updates all found skills
  • <names>: Updates only specified skills
  • Update process for each skill:
    1. Temporarily move OVERRIDE.md if it exists
    2. Delete the skill directory
    3. Copy fresh version from remote repo
    4. Restore OVERRIDE.md if it existed
  • Silently skips local-only skills (not in remote) during --all
  • Notes error and continues if specified skill not installed locally
  • Skills must be explicitly added before they can be updated
  • Regenerates skills/README.md

skill onboard

  • Prints the AGENTS.md block with instructions on where/how to add it
  • Shows the source repo being used
  • Does not modify any files

skill env

  • Displays the active config file path and current configuration values
  • Human-readable format: 
    Config: /path/to/.config/skills/skills.json
Repository: https://github.com/DockYard/skills
Branch: main
  • Shows which ref type is active (branch/tag/sha) if specified

Error Handling

  • No git installed: Error with message "Error: This tool requires git to be installed"
  • Repo unreachable: Descriptive error explaining why (network, auth, doesn't exist)
  • Invalid branch/tag/sha: Error message indicating the ref doesn't exist
  • Multiple ref types in config: Error requiring only one of branch/tag/sha
  • No skills/ directory: Error directing user to run skill init
  • Error output: Individual errors go to stderr, success messages to stdout
  • Exit codes: Non-zero if any errors occurred, even if some operations succeeded

Git Operations (No Caching)

  • All operations fetch directly from remote repository
  • Uses git sparse checkout to fetch only skills/ directory
  • Temporary operations use system temp directory (std.fs.tmpDir())
  • Immediate cleanup after each operation
  • Requires git to be installed (dependency)

6) Generated Content Templates

skills/README.md

Generated during skill init and regenerated on add/remove/update. Uses imperative language optimized for LLM comprehension.

Example:

# Skills System

## Instructions for AI Agents

You MUST follow this precedence order when reading skills:

1. Read `SKILL.md` for the base skill instructions
2. If `OVERRIDE.md` exists in the same directory, it takes precedence and overrides `SKILL.md`
3. Always check for `OVERRIDE.md` before applying skill instructions

## Discovering Skills

To discover available skills in this project:

1. List all directories under `skills/`
2. Each directory represents one skill
3. Read the `SKILL.md` file in each skill directory for instructions
4. Check for `OVERRIDE.md` which contains local customizations

## Precedence Rules

- `OVERRIDE.md` is local-only and takes absolute precedence over `SKILL.md`
- `OVERRIDE.md` is gitignored to keep local customizations out of version control
- When both files exist, apply `OVERRIDE.md` instructions instead of `SKILL.md`
- Never assume all skills exist; only use those present under `skills/`

## Using Skills

When applying skills to your work:

1. Read `AGENTS.md` first for project-level behavior
2. Read this `skills/README.md` for system rules
3. For each required skill:
   - Read `skills/<name>/SKILL.md` first
   - If `skills/<name>/OVERRIDE.md` exists, use it instead

## Examples

If you need to apply the "testing" skill:
- Check if `skills/testing/` exists
- Read `skills/testing/SKILL.md`
- Check if `skills/testing/OVERRIDE.md` exists and use it if present

## Maintenance

Skills are managed using the `skill` CLI:

- Add skills: `skill add <name>`
- Remove skills: `skill remove <name>`
- Update skills: `skill update --all` or `skill update <name>`
- List available skills: `skill list`

AGENTS.md Block (Printed by skill init and skill onboard)

Output format when printed to terminal:

Source repository: https://github.com/DockYard/skills

Add the following block to your AGENTS.md file:

<!-- BEGIN: skills-system -->
Agents MUST resolve guidance in this order:

1) Project-level behavior: `AGENTS.md` (this file)
2) Skills system rules: `skills/README.md`
3) For each required skill:
   - Read `skills/<name>/SKILL.md`
   - If `skills/<name>/OVERRIDE.md` exists, its guidance OVERRIDES `SKILL.md`

Never assume all skills exist; only use those present under `skills/`.
If two skills conflict, prefer the more specific skill's OVERRIDES, then SKILL.md.
<!-- END: skills-system -->

7) Update Behavior (No Versions)

  • skill update always fetches from the configured ref (branch/tag/sha) or HEAD
  • No per-skill version tracking
  • Always overwrites vendored skill files
  • Always preserves OVERRIDE.md files
  • Users manage version control conflicts via their own git workflow

8) Zig Implementation Approach

Target

  • Zig 0.15.2
  • Portable across macOS, Linux, Windows

Core Modules

  • main.zig - Entry point, command routing, argument parsing
  • config.zig - Config file loading (JSON5 parsing), hierarchy resolution
  • git.zig - Git operations (sparse checkout, list skills, fetch to temp)
  • project.zig - Project structure management (init, validate)
  • vendor.zig - Skill copying, OVERRIDE.md preservation
  • render.zig - Generate skills/README.md and AGENTS.md block
  • commands/ - Individual command implementations

Standard Library Usage

  • std.fs - File operations, temp directory
  • std.process - Shell out to git commands
  • std.json - JSON5 parsing for config files
  • std.fmt - String formatting and output
  • std.mem - Memory operations
  • Built-in argument parsing or minimal hand-rolled parser

9) Distribution & Installation

Homebrew (macOS/Linux)

Provide pre-built binaries via Homebrew tap:

class Skill < Formula
  desc "Vendor and manage LLM skills from a central repository"
  homepage "https://github.com/DockYard/skill"
  version "0.1.0"
  
  on_macos do
    if Hardware::CPU.arm?
      url "https://github.com/DockYard/skill/releases/download/v0.1.0/skill-macos-arm64.tar.gz"
      sha256 "<sha256>"
    else
      url "https://github.com/DockYard/skill/releases/download/v0.1.0/skill-macos-x86_64.tar.gz"
      sha256 "<sha256>"
    end
  end
  
  on_linux do
    url "https://github.com/DockYard/skill/releases/download/v0.1.0/skill-linux-x86_64.tar.gz"
    sha256 "<sha256>"
  end
  
  def install
    bin.install "skill"
  end
  
  test do
    system "#{bin}/skill", "--version"
  end
end

Shell Script Installer (wget/curl)

Provide an install script that:

  1. Detects OS and architecture
  2. Downloads appropriate pre-built binary from GitHub releases
  3. Verifies checksum
  4. Installs to /usr/local/bin/skill (with sudo) or $HOME/.local/bin/skill (without sudo)
  5. Makes executable
  6. Verifies installation

Example usage:

curl -fsSL https://raw.githubusercontent.com/DockYard/skill/main/install.sh | sh

Or:

wget -qO- https://raw.githubusercontent.com/DockYard/skill/main/install.sh | sh

Build From Source

Requirements:

  • Zig 0.15.2
  • Git

Steps:

git clone https://github.com/DockYard/skill.git
cd skill
zig build -Doptimize=ReleaseSafe
# Binary located at zig-out/bin/skill

10) Edge Cases & Guardrails

Git Dependency

  • Every command that needs git checks for availability first
  • Clear error message if git not installed

Network & Repository Issues

  • Descriptive errors for unreachable repos
  • Auth errors with actionable messages
  • Invalid ref (branch/tag/sha) with clear feedback

Conflicts & Existing Files

  • skill init errors if skills/ exists
  • skill add errors if skill already exists (stops processing)
  • skill remove prompts if OVERRIDE.md exists, continues if declined

Configuration Validation

  • Validates only one of branch/tag/sha is specified
  • Clear error messages for invalid JSON5 syntax
  • Graceful handling of missing config (uses defaults)

Skill Operations

  • Empty skill directories are copied as-is during update
  • Local-only skills silently skipped during skill update --all
  • Missing skills noted but processing continues for batch operations

11) What You Get

  • ✅ Single centralized skills repository
  • ✅ Per-project vendoring (only what you need)
  • ✅ Optional local overrides (gitignored)
  • ✅ No version complexity (always use specified ref or latest)
  • ✅ Portable single-binary CLI (macOS, Linux, Windows)
  • ✅ Multiple installation methods (Homebrew, script, source)
  • ✅ Clear LLM instructions via generated README
  • ✅ Simple configuration hierarchy
  • ✅ No caching complexity (direct remote fetches)

12) Command Quick Reference

# Initialize project
skill init                              # Use default/global config
skill init --repo <URL>                 # Set local repo
skill init --repo <URL> --branch <name> # Set repo and branch
skill init --repo <URL> --tag <name>    # Set repo and tag
skill init --repo <URL> --sha <hash>    # Set repo and specific commit

# Discover and add skills
skill list                              # List all available skills
skill add <name>                        # Add one skill
skill add <name1> <name2> <name3>       # Add multiple skills

# Remove skills
skill remove <name>                     # Remove one skill
skill remove <name1> <name2>            # Remove multiple skills

# Update skills
skill update                            # Show usage and installed skills
skill update --all                      # Update all installed skills
skill update <name>                     # Update one skill
skill update <name1> <name2>            # Update multiple skills

# Information
skill env                               # Show config path and values
skill onboard                           # Print AGENTS.md block

# Workflow
skill init                              # Initialize project
skill list                              # Browse available skills
skill add testing docs                  # Add skills you need
# ... work on project ...
skill update --all                      # Update all skills to latest

13) Example Workflows

Starting a New Project

cd my-project
skill init
skill list
skill add swift-style testing documentation
# Manually create skills/swift-style/OVERRIDE.md if needed
git add skills/
git commit -m "Add skills system"

Using a Custom Skills Repo

skill init --repo https://github.com/myorg/custom-skills --branch develop
skill add custom-skill

Pinning to a Specific Version

skill init --repo https://github.com/DockYard/skills --tag v1.2.0
skill add testing
# Skills are pinned to v1.2.0

Local Customization

skill add testing
# Manually create and edit:
vim skills/testing/OVERRIDE.md
# Add local-only customizations
# File is gitignored, won't be overwritten by updates

Updating Skills

# Update everything
skill update --all

# Update specific skills
skill update testing documentation

# Check what's installed first
skill update

14) Future Considerations (Out of Scope for v1)

  • Skill dependencies (one skill requiring another)
  • Skill validation/linting
  • Interactive mode for adding skills
  • Dry-run mode for updates
  • Skill templates/scaffolding
  • Multiple skills repos per project
  • Skill search/filtering
  • Publishing skills back to central repo