A package starts with this shape:

my-package/
├── agh.package.toml
├── instructions/
│   ├── AGENTS.md
│   └── CLAUDE.md
└── skills/
    └── reviewer/
        └── SKILL.md

Create a template:

agh package init ./my-package --domain acme --name onboarding --version 1.0.0

The manifest starts as:

domain = "acme"
name = "onboarding"
version = "1.0.0"
description = "TODO"

Useful starter flags:

• --with-agents creates instructions/AGENTS.md.
• --with-claude creates instructions/CLAUDE.md.
• --with-skill NAME creates skills/NAME/SKILL.md.

Allowed files:

• agh.package.toml
• instructions/AGENTS.md
• instructions/CLAUDE.md
• skills/<name>/SKILL.md

Rules:

• A package can contain instructions, skills, or both.
• It must include at least one instruction file or skill.
• version must be exact SemVer, such as 1.0.0.
• Published versions are immutable. Publish 1.0.1 for changes.
• Do not publish latest. Use latest only when assigning packages to projects.
• Use UTF-8 text files. Do not include symlinks.

Publish and list packages:

agh package publish ./my-package
agh package list

Example publish output:

Published acme/onboarding@1.0.0.
Package ID: pkg_...
Checksum: sha256:...

A project is an AGH record linked to one git repository.

agh project create "Agent Guidance Hub" \
  --git-url https://github.com/giulianotesta7/AgentGuidanceHub.git
agh project list
agh project describe prj_...
agh project update prj_... --name "App API"
agh project deactivate prj_...
agh project member list prj_...

Project commands that take a project reference accept prj_... ids or exact project names. All-digit values are treated as ids, and project names cannot contain only digits.

Assign packages through the unified package commands with exactly one target scope (--project or --collection):

agh package assign acme/onboarding@latest --project prj_...
agh package list --project prj_...
agh package describe acme/onboarding@1.0.0
agh package activate acme/onboarding@latest --project prj_...
agh package deactivate acme/onboarding@latest --project prj_...
agh package unassign acme/onboarding@latest --project prj_...

Package inputs accept pkgv_..., domain/name@version, and exact name@version refs. No-domain refs must match a single package domain, otherwise AGH reports a conflict. Use an exact version to pin the project. Use latest with domain-qualified refs when the project should resolve to the newest published version during pull. package describe PACKAGE_REF@latest resolves to the highest SemVer version.

The server keeps assignment ids internal: activate, deactivate, and unassign look up the existing assignment by package ref plus target scope. When a package is not assigned, the failure names the package ref, scope, and scope id and suggests agh package list --<scope> <id>.

During workspace pull, AGH writes the resolved concrete version and checksum to .agh/lock.toml.

Collections group skill-only packages that members install through agh skill .... Owners and admins manage collections with the agh collection commands. These admin commands are separate from the consumer agh skill ... flow.

agh collection create "Team Skills" --description "Shared review skills"
agh collection list
agh collection describe "Team Skills"
agh collection update "Team Skills" --name "Review Skills"
agh collection deactivate "Review Skills"

Collection commands that take a collection reference accept col_... ids or exact active collection names. Canonical ids skip name resolution; exact names resolve through the active-collection by-name endpoint.

Assign skill-only packages to a collection through the unified package commands with --collection:

agh package assign acme/reviewer@latest --collection "Team Skills"
agh package list --collection "Team Skills"
agh package activate acme/reviewer@latest --collection "Team Skills"
agh package deactivate acme/reviewer@latest --collection "Team Skills"
agh package unassign acme/reviewer@latest --collection "Team Skills"

Collection packages must be skill-only: AGH rejects packages that contain instructions/AGENTS.md, instructions/CLAUDE.md, or no skills, and the CLI surfaces that server validation. Package inputs accept pkgv_..., domain/name@version, and exact name@version refs. Assignment requires both the collection and the package reference; there is no interactive picker, since only the server can validate skill-only packages.

Global skills are collection-backed tools installed into the selected target's native user-level skill directory. A collection is an AGH-managed group of skill-only packages made available by the server; global skills are separate from workspace package assignments.

Target resolution for skill install follows this order: an explicit --target, the workspace target (.agh-cache/preferences.toml), the global target, then an interactive prompt. In non-interactive mode AGH exits with code 2 instead of prompting.

If no target is saved and --target is omitted, AGH prompts with:

Select the target for global skills:

Install paths:

• OpenCode global skills: ~/.config/opencode/skills
• Claude global skills: ~/.claude/skills

Global skill state is local user state under XDG_STATE_HOME/agh or ~/.local/state/agh; it does not change workspace pull behavior or .agh/lock.toml.

There is no both option. If no target is selected, interactive agh pull asks which target to use. Skip exits with code 2 and writes nothing.

Instruction files use managed blocks:

<!-- AGH-BEGIN package="<package-ref>" artifact="instructions/AGENTS.md" checksum="sha256:..." -->
Project instructions from AGH live here.
<!-- AGH-END package="<package-ref>" -->

If you edit inside the block, the next agh pull exits with conflict code 3. Use agh pull --force when AGH should replace it.

Skills go where agents already look:

.claude/skills/<skill>/SKILL.md
.opencode/skills/<skill>/SKILL.md

AGH tries a relative symlink to .agh-cache/packages/.... If the OS rejects symlinks, AGH copies the file. The lockfile records the mode:

[[packages]]
package_ref = "acme/onboarding@1.0.0"

[[artifacts]]
package_ref = "acme/onboarding@1.0.0"
path = "skills/reviewer/SKILL.md"
target_path = ".opencode/skills/reviewer/SKILL.md"
mode = "symlink" # or mode = "copy"
source = ".agh-cache/packages/acme/onboarding/1.0.0/skills/reviewer/SKILL.md"

Commit shared workspace state:

• .agh/project.toml
• .agh/lock.toml
• generated AGENTS.md / CLAUDE.md when your team wants those reviewed
• generated .claude/skills/ or .opencode/skills/ when your team wants skills reviewed

Do not commit local cache state:

.agh-cache/

AGH downloads packages to .agh-cache/packages/ and stores each developer's target choice in .agh-cache/preferences.toml. If skill targets are symlinks, a fresh clone needs agh pull to rebuild the cache before those links resolve.

Exit codes: