Source: skull · skull.md · updated 2026-06-03 · 🔒 secret gist

Synced verbatim from gist.github.com/bl9.

I want you to create a thorough product and technical plan for a Go-based command-line tool that manages AI-agent “skills” hosted in GitHub repositories.

The tool should behave like a terminal-native extension manager for AI coding tools, similar in spirit to VS Code extensions, but focused only on GitHub-hosted skill directories.

Core goal: Build a single Go executable that allows users to register GitHub skill sources, discover valid skills from those sources, browse/search them, install them, validate them, detect updates, preview changes, update them, remove them, and use shell autocomplete and a polished TUI.

Important constraint: The user should install only one executable binary. The tool must not require users to install Git, SQLite, Node, Python, unzip, jq, or any external service. Any local storage must be embedded and created automatically by the executable.

Storage requirement: Do not use plain JSON as the primary internal store. Plan for a solid embedded local storage system suitable for many sources, many skills, autocomplete caching, discovery results, installed state, update status, file hashes, and TUI filtering. Prefer embedded SQLite unless there is a stronger reason to choose another embedded store. JSON may still be used for portable exports, lockfiles, or project-level configuration, but not as the main internal database.

GitHub-only scope: The tool should support GitHub only. It should not attempt to support GitLab, Bitbucket, generic Git, or marketplace payments in the initial design.

Discovery model: Do not scan all of GitHub. Do not scan entire repositories. Discovery must be explicit and bounded.

A user should register one or more GitHub skill sources. Each source should include:

  • source name
  • GitHub repo, for example owner/repo
  • ref, branch, tag, or commit
  • exact root path where skills are expected to live, for example skills/ or approved/skills/

Example: skill source add agensi github:agensi/skills@main:skills

The tool should discover only under configured source paths.

A single repo may have multiple source paths, for example:

  • github:agensi/skills@main:skills
  • github:agensi/skills@main:experimental
  • github:company/ai-skills@main:approved

Discovery should support:

  • source add/list/edit/remove/enable/disable/test
  • discover all enabled sources
  • refresh catalog and update status
  • autocomplete based on discovered catalog
  • TUI browsing based on discovered catalog

Discovery validation: The tool must verify that a configured source path is actually a skills root, not just a random GitHub directory.

A source path should be considered valid only if it contains a recognized skill index file or contains valid skill directories according to strict rules.

Preferred model: A source root may contain a skills index file, for example skills.index.json, listing skill directories and metadata.

Fallback model: If no index exists, discovery may inspect direct child directories only, or a carefully bounded max depth. It must not recursively scan unlimited directories. It should detect valid skill directories by the presence of required files.

Skill validation: A valid skill directory should include at minimum:

  • skill.json manifest
  • SKILL.md entry file

The tool must validate both during discovery and again before install/update.

Validation should reject or warn on:

  • missing skill.json
  • missing SKILL.md
  • invalid manifest schema
  • manifest name mismatch
  • invalid or duplicate skill names
  • paths outside the configured source root
  • path traversal such as ../
  • absolute paths
  • symlinks unless explicitly allowed
  • Git submodules unless explicitly allowed
  • hidden/sensitive files such as .env, *.pem, *.key
  • unexpected files not included by the manifest allowlist
  • huge files over configured size limits
  • binary files unless explicitly allowed
  • directories that are near the source path but are not actually skills

The plan should include how invalid directories are reported to the user during discovery without breaking discovery for the whole source.

Installation model: The installer should download only the selected skill files from GitHub. It should not clone the whole repo. It should use GitHub APIs to fetch the tree and blobs/content for only the relevant paths.

Before installing, the tool should show an install preview:

  • skill name
  • source
  • resolved commit
  • target
  • install path
  • files to install
  • warnings
  • validation result

Install should be atomic:

  • download to temporary location
  • validate content
  • backup existing installation
  • swap into final target directory
  • write local metadata
  • support rollback

Target model: The tool should support installing skills into different AI-agent targets, for example:

  • Claude Code
  • OpenClaw
  • Codex CLI
  • Cursor, if applicable

The plan should define a clean target abstraction, because a skill may be installed for one target and not another.

Revision and update model: Do not rely on GitHub Releases. Do not assume skills have formal versions. Skills may only be Markdown files, and a single text change can materially change behavior.

The tool should track:

  • optional human version from skill.json
  • GitHub ref being tracked, for example main
  • resolved installed commit
  • latest resolved commit
  • content hash of the actual skill files
  • file-level hashes
  • changed files

Update detection should be based primarily on content changes in the actual skill files, not only on repo commit changes and not only on manifest version changes.

The tool should clearly show:

  • current version and latest version if available
  • current revision and latest revision
  • whether content changed
  • which files changed
  • whether version changed
  • whether the skill is pinned
  • whether the upstream source disappeared
  • whether local files were modified

The user must be able to run:

  • skill check
  • skill outdated
  • skill diff
  • skill update
  • skill update --all
  • skill pin
  • skill rollback

Updates should never be applied silently by default. The user should see what changed before applying, especially for Markdown content changes.

Autocomplete: The CLI should provide excellent shell autocomplete for Bash, Zsh, Fish, and PowerShell.

Autocomplete must not call GitHub directly. It should query the local embedded database/cache only.

Autocomplete should support:

  • install: discovered but not installed skills
  • update: installed skills with updates available
  • remove: installed skills
  • source commands: configured source names
  • target names
  • tags or filters where useful

TUI: The tool should include a polished terminal UI written in Go.

The TUI should include screens such as:

  • Store / Catalog
  • Installed
  • Updates
  • Sources
  • Skill details
  • Diff / change preview
  • Doctor / health check

The TUI should allow:

  • search
  • filtering by source, target, installed status, update status, tags
  • install/update/remove actions
  • viewing validation warnings
  • viewing changed files
  • refreshing sources
  • adding/editing sources

CLI and CI: The tool should also work well in non-interactive mode.

Support:

  • --json output for machine-readable commands
  • --ci mode
  • deterministic exit codes
  • no prompts in CI mode
  • sync from project lockfile
  • check for drift or updates
  • project-level source and lock files for teams

Project-level files: The plan should include optional project files such as:

  • skills.sources.json
  • skills.lock

These files should be portable and reviewable, but the main internal local store should still be embedded storage.

Doctor/repair: The tool should include a doctor command that can detect and optionally fix:

  • missing target directories
  • broken installed metadata
  • stale cache
  • missing source paths
  • disabled or unreachable sources
  • invalid installed skills
  • local modifications
  • missing upstream skills
  • autocomplete cache issues

Security and trust: The plan should include safety and trust rules:

  • no arbitrary script execution during install
  • no implicit executable file installation unless allowed
  • clear validation before install/update
  • content hashes
  • provenance metadata for every installed skill
  • backup and rollback
  • transparent diff before update
  • support for GitHub token via env var or stored login
  • no GitHub calls during autocomplete

Expected output: Produce a complete product and technical plan, but do not write implementation code.

Structure the answer with:

  1. Product summary
  2. Primary workflows
  3. Source and discovery model
  4. Skill validation model
  5. Storage architecture
  6. Update/revision tracking model
  7. CLI command design
  8. TUI design
  9. Autocomplete design
  10. Install/update/remove lifecycle
  11. CI and lockfile behavior
  12. Data model at a conceptual level
  13. Failure modes and how the tool should report them
  14. MVP scope
  15. Future enhancements
  16. Open design questions

Keep the plan practical, implementation-oriented, and opinionated. Avoid vague marketplace language. The product should do one thing very well: manage GitHub-hosted AI skills from explicitly configured GitHub source paths.