Go-first workflows for managing, installing, and mounting AI agent skills across projects. Supports Claude Code, Codex, and Gemini CLI with local-only execution, containerised security audits, and symlink-based project mounting.

• Overview
• Prerequisites
• Quick Start
• Installation
  • From source
  • Standalone binary from GHCR
  • Docker image
• CLI Reference
  • skills
  • add-skill
  • mount-skills
  • audit
• Make Targets
• Skill Management
  • Install all skills
  • Add individual skills
  • Remove skills
  • Mount skills to external projects
  • Validate skills
• Security
  • Design principles
  • Security scanning
  • Docker socket safety
• Configuration
  • Environment variables
  • Docker secrets
• Development
  • Project structure
  • Building
  • Code formatting and linting
  • Testing
  • CI/CD
• License
• Contributing

This project provides a Go CLI and Make-based workflow for:

• Local-only skill install/add inside this repository
• External project linking via .agents mount-style symlinks
• Containerised security audit scanning with behavioural and YARA-based analysis

Skills are sourced from Vercel's skill.sh registry (vercel-labs/agent-skills) and stored under .agents/skills/. They work with Claude Code, Codex, and Gemini CLI agents. All operations run locally — your code and prompts are never sent to third-party services for skill management.

What is skill.sh? skill.sh is Vercel's open registry of agent skills. This project uses it as the default source for make skills and make add-skill. The registry provides curated, community-contributed skills that enhance AI coding agents with domain-specific capabilities. Skills are downloaded once and stored locally — no ongoing connection to the registry is required.

# 1. Configure environment
cp .env.example .env

# 2. Install skills into this repository
make skills

# 3. Mount skills to your project
make mount-skills TARGET_PROJECT=/absolute/path/to/your/project

# 4. Validate symlinks
make skills-validate TARGET_PROJECT=/absolute/path/to/your/project

Clone the repository and build the Go CLI binary:

git clone https://github.com/gocanto/skills.git
cd skills
make build   # outputs binary to dist/skills

Download the prebuilt binary package from GHCR without cloning this repository.

# Optional for private packages
docker login ghcr.io

# Choose one tag: vX.Y.Z-linux-amd64, vX.Y.Z-linux-arm64, vX.Y.Z-darwin-amd64, vX.Y.Z-darwin-arm64
# Or use latest: latest-linux-amd64, latest-linux-arm64, latest-darwin-amd64, latest-darwin-arm64
docker pull ghcr.io/gocanto/skills-bin:latest-darwin-arm64

container_id="$(docker create ghcr.io/gocanto/skills-bin:latest-darwin-arm64)"
docker cp "${container_id}:/skills" ./skills
docker rm "${container_id}"
chmod +x ./skills

./skills help

Standalone command equivalents for Make workflows:

# make skills
./skills skills --repo-root /absolute/path/to/repo

# make add-skill SKILLS='skill-a,skill-b'
./skills add-skill --repo-root /absolute/path/to/repo --skills 'skill-a,skill-b'

# make mount-skills TARGET_PROJECT=/absolute/path/to/project
./skills mount-skills --project /absolute/path/to/project --source-root /absolute/path/to/repo --agents-source /absolute/path/to/repo/.agents

# make audit ROOT_PATH=/absolute/path/to/repo
./skills audit --root /absolute/path/to/repo

Notes:

• skills and add-skill require Docker at runtime and use a runner image (SKILLS_RUNNER_IMAGE or --runner-image).
• mount-skills links .agents and .claude into the target project.
• mount-skills uses --source-root (env: SKILLS_ROOT, default: current working directory absolute path) and --agents-source (env: AGENTS_DIR, default: <skills-root>/.agents).
• If the provided source paths contain neither .agents nor .agents/skills, mount-skills extracts embedded content to cache and uses that location as the source for the links.

Build and run the CLI entirely inside Docker (no host Go required):

docker build -f docker/Dockerfile.manager -t skills-cli:local .
docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PWD":/workspace/skills \
  -w /workspace/skills \
  skills-cli:local help

Go CLI (development mode):

go run ./manager/cmd/skills <command> [flags]

--repo-root, --source-root, --agents-source, and --root require absolute paths. Use $(pwd) as a shortcut during development.

Install all skills into this repository from the skill.sh registry.

go run ./manager/cmd/skills skills --repo-root /absolute/path/to/repo --runner-image ghcr.io/gocanto/skills-runner:latest

Add one or more specific skills to this repository from the skill.sh registry.

go run ./manager/cmd/skills add-skill --repo-root /absolute/path/to/repo --skills 'skill-a,skill-b'

Link skills into an external project via symlinks.

go run ./manager/cmd/skills mount-skills --project /absolute/path/to/project --source-root /absolute/path/to/repo --agents-source /absolute/path/to/repo/.agents

Creates two symlinks in the target project:

• <project>/.agents -> <source-root>/.agents (or embedded fallback)
• <project>/.claude -> <source-root>/.agents/skills (or embedded fallback)

If either target path already exists, it is moved to a timestamped backup before replacement.

Run containerised security scanning on installed skills.

go run ./manager/cmd/skills audit --root /absolute/path/to/repo

Default scan profile: --severity low --use-behavioral --yara-mode strict --fail-on-findings

Populate or refresh the .agents/skills directory with all available skills from the skill.sh registry:

make skills

Optional overrides:

make skills \
  SOURCE=vercel-labs/agent-skills \
  SKILLS='*' \
  DISABLE_TELEMETRY=1 \
  COLOR=always

make skills and make add-skill are local-only for this repository. make skills TARGET_PROJECT=... is rejected — use make mount-skills TARGET_PROJECT=... for external projects.

make add-skill SKILLS='skill-a'
make add-skill SKILLS='skill-a,skill-b'
make add-skill SKILLS='*'

make add-skill is locked to vercel-labs/agent-skills (skill.sh) and does not support other sources.

Remove a skill from this repository:

git rm -r .agents/skills/skill-a

Remove mounted links from an external project:

rm -f /absolute/path/to/project/.agents
rm -f /absolute/path/to/project/.claude

Expose skills in another project without cloning this repository there:

make mount-skills TARGET_PROJECT=/absolute/path/to/your/project

This always enforces:

• <project>/.agents -> <source-root>/.agents (or embedded fallback)
• <project>/.claude -> <source-root>/.agents/skills (or embedded fallback)

If either target path already exists (file/dir/symlink), it is moved to a timestamped backup and replaced.

Verify that symlinks were correctly created in the target project:

make skills-validate TARGET_PROJECT=/absolute/path/to/your/project

This checks that both .agents and .claude symlinks exist and point to valid targets. Broken or missing symlinks are reported as errors.

• Local-Only Execution: All skills are stored and executed locally within your environment. Your code and prompts are never sent to third-party services for skill management.
• Containerised Audits: The make audit command runs a containerised security scanner that performs behavioural and static analysis (via YARA) on all skills to detect malicious patterns, prompt injections, or unauthorised data exfiltration risks.
• Docker Socket Isolation: Docker-based workflows that require host Docker daemon control are explicitly protected by the ALLOW_DOCKER_SOCK opt-in mechanism.
• Immutability: When mounting skills, existing paths are backed up rather than overwritten, ensuring you never lose local configurations.

make audit

Default profile:

--severity low --use-behavioral --yara-mode strict --fail-on-findings

Optional overrides:

make audit \
  ROOT_PATH=/absolute/path/to/repo \
  SKILL_SCANNER_PATH=.agents/skills \
  SKILL_SCANNER_ARGS='--severity critical' \
  COLOR=auto

docker/compose.turbo.yml and docker/compose.tests.yml mount /var/run/docker.sock, which gives containers host Docker daemon control.

• Treat these workflows as host-root equivalent.
• Use only in trusted local/CI environments.
• Explicitly opt in with ALLOW_DOCKER_SOCK=true.

ALLOW_DOCKER_SOCK=true make turbo-build
ALLOW_DOCKER_SOCK=true make turbo-test
ALLOW_DOCKER_SOCK=true make test

Copy the example file and edit for your local environment:

cp .env.example .env

.env can include secrets locally; never commit your real .env.

Go commands support Docker-style file inputs via *_FILE variables. The *_FILE variant takes precedence over the direct value.

SKILLS_ROOT_FILE=/run/secrets/skills_root
AGENTS_DIR_FILE=/run/secrets/agents_dir
SKILLS_RUNNER_IMAGE_FILE=/run/secrets/skills_runner_image
SKILL_SCANNER_ARGS_FILE=/run/secrets/skill_scanner_args

All _FILE variants available: SOURCE_FILE, SKILLS_FILE, DISABLE_TELEMETRY_FILE, MANAGE_CLAUDE_LINK_FILE, SKILLS_RUNNER_IMAGE_FILE, SKILLS_ROOT_FILE, AGENTS_DIR_FILE, SKILL_SCANNER_PATH_FILE, SKILL_SCANNER_ARGS_FILE.

.
├── .agents/skills/          # Installed agent skills
├── .github/workflows/       # CI/CD pipelines
├── docker/                  # Dockerfiles and Compose configs
│   ├── Dockerfile.binary    # Standalone binary build
│   ├── Dockerfile.manager   # Manager CLI image
│   ├── Dockerfile.skills    # Skills runner image
│   ├── Dockerfile.tests     # Test runner
│   ├── Dockerfile.tools     # Development tools (goimports)
│   ├── Dockerfile.turbo     # Turborepo runner
│   ├── compose.skills.yml   # Skills workflows
│   ├── compose.tests.yml    # Test execution
│   ├── compose.tools.yml    # Formatting tools
│   └── compose.turbo.yml    # Turbo-based tasks
├── manager/                 # Go CLI source
│   └── cmd/skills/          # CLI entrypoint
├── scripts/                 # Build and CI scripts
│   └── mk/                  # Makefile includes
├── .env.example             # Environment template
├── Makefile                 # Primary task runner
├── go.work                  # Go workspace (1.26)
└── turbo.json               # Turborepo configuration

make build   # outputs dist/skills

# Format with gofmt
make format

# Format with gofmt + goimports via Docker (with -local skills)
make format imports

# Lint: gofmt check + go vet
make lint

All tests are Go-based and include Testcontainers-driven functional/e2e coverage. By default, tests run inside Docker using turbo run .... Set USE_DOCKER=false to run directly on your host.

# Run all tests (unit, functional, e2e) and check coverage
make test

# Individual test suites
make test-unit
make test-functional
make test-e2e

# Check coverage threshold (requires previous test runs)
make test-coverage

# Run all tests with host Go (bypassing Docker)
make test USE_DOCKER=false

Test configuration (from scripts/mk/tests.mk):

Coverage outputs:

• Unit: .cache/coverage/unit-*.out
• Functional: .cache/coverage/functional.out
• E2E: .cache/coverage/e2e.out

Tests workflow (tests.yml) — runs on pull requests:

• Lint (make lint)
• Unit tests (make test-unit)
• Functional tests (make test-functional)
• E2E tests (make test-e2e)
• Coverage gate (make test-coverage) — merges all profiles and checks a threshold

Release workflow (release.yml) — runs on version tags (v*):

• Validates embedded .agents archive
• Builds and pushes manager image to GHCR (multi-arch: linux/amd64, linux/arm64)
• Builds and pushes runner image to GHCR (multi-arch)
• Builds and pushes standalone binary packages for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64

This project is licensed under the MIT Licence – see the LICENCE file for details.

Contributions are welcome! Please feel free to submit a Pull Request.

Thanks, Gus.