GitLabgitlab-org
cli
main
1// Package bundled is the source for agent skills that ship inside the
2// glab binary via go:embed. The skill type itself lives in the sibling
3// `skill` package; this package only knows how to discover and load
4// from the embedded FS.
5//
6// The on-disk layout under assets/ follows the Agent Skills specification
7// (https://agentskills.io/specification): each top-level directory is a skill
8// whose name matches the directory, and must contain a SKILL.md plus any
9// optional supporting files (scripts/, references/, assets/, etc.).
10package bundled
12import (
13 "embed"
14 "errors"
15 "fmt"
16 "io/fs"
17 "path"
18 "sort"
19 "strings"
20 "sync"
22 "gitlab.com/gitlab-org/cli/internal/commands/skills/skill"
23)
25// ErrNotFound is returned by Get when no bundled skill has the
26// requested name. Callers can errors.Is against it to distinguish
27// "this source doesn't have it" from a registry-load failure.
28var ErrNotFound = errors.New("not in bundled skills")
30const assetsDir = "assets"
32//go:embed all:assets
33var fsys embed.FS
35var (
36 loadOnce sync.Once
37 loaded []skill.Skill
38 loadErr error
39)
41// All returns every bundled skill, sorted by name. Files are populated.
42func All() ([]skill.Skill, error) {
43 loadOnce.Do(load)
44 if loadErr != nil {
45 return nil, loadErr
46 }
47 out := make([]skill.Skill, len(loaded))
48 copy(out, loaded)
49 return out, nil
50}
52// Get returns the bundled skill with the given name.
53func Get(name string) (skill.Skill, error) {
54 skills, err := All()
55 if err != nil {
56 return skill.Skill{}, err
57 }
58 for _, s := range skills {
59 if s.Name == name {
60 return s, nil
61 }
62 }
63 return skill.Skill{}, fmt.Errorf("%w: %q", ErrNotFound, name)
64}
66func load() {
67 entries, err := fs.ReadDir(fsys, assetsDir)
68 if err != nil {
69 loadErr = fmt.Errorf("reading bundled skills: %w", err)
70 return
71 }
73 skills := make([]skill.Skill, 0, len(entries))
74 for _, entry := range entries {
75 if !entry.IsDir() {
76 continue
77 }
78 s, err := loadSkill(entry.Name())
79 if err != nil {
80 loadErr = err
81 return
82 }
83 skills = append(skills, s)
84 }
86 sort.Slice(skills, func(i, j int) bool { return skills[i].Name < skills[j].Name })
87 loaded = skills
88}
90func loadSkill(dirName string) (skill.Skill, error) {
91 skillRoot := path.Join(assetsDir, dirName)
92 files, err := collectFiles(skillRoot)
93 if err != nil {
94 return skill.Skill{}, fmt.Errorf("reading skill %q: %w", dirName, err)
95 }
97 skillMD, ok := files[skill.FileName]
98 if !ok {
99 return skill.Skill{}, fmt.Errorf("skill %q is missing required %s", dirName, skill.FileName)
100 }
102 fm, err := skill.ParseFrontmatter(skillMD)
103 if err != nil {
104 return skill.Skill{}, fmt.Errorf("parsing frontmatter in %s/%s: %w", dirName, skill.FileName, err)
105 }
106 // Minimum checks needed for load to function — name keys the registry
107 // and must match the directory; description is rendered by `skills list`.
108 // Full Agent Skills spec compliance (regex, length caps, etc.) is left to
109 // hand-review and upstream tooling.
110 if fm.Name == "" {
111 return skill.Skill{}, fmt.Errorf("%s/%s: frontmatter is missing 'name'", dirName, skill.FileName)
112 }
113 if fm.Name != dirName {
114 return skill.Skill{}, fmt.Errorf("%s/%s: frontmatter name %q does not match directory %q", dirName, skill.FileName, fm.Name, dirName)
115 }
116 if fm.Description == "" {
117 return skill.Skill{}, fmt.Errorf("%s/%s: frontmatter is missing 'description'", dirName, skill.FileName)
118 }
120 return skill.Skill{
121 Name: fm.Name,
122 Description: fm.Description,
123 Source: skill.SourceBundled,
124 Files: files,
125 }, nil
126}
128// collectFiles walks the embedded skill directory and returns every regular
129// file keyed by its path relative to the skill root.
130//
131// Paths are canonicalized with path.Clean and verified to be rooted under
132// skillRoot before the file is read. embed.FS doesn't expose symlinks or
133// allow ".." references at build time, so today this is defensive coding
134// rather than a real attack surface — but it documents the invariant and
135// guards against future refactors that swap embed.FS for a real
136// filesystem source.
137func collectFiles(skillRoot string) (map[string][]byte, error) {
138 files := map[string][]byte{}
139 err := fs.WalkDir(fsys, skillRoot, func(p string, d fs.DirEntry, err error) error {
140 if err != nil {
141 return err
142 }
143 if d.IsDir() {
144 return nil
145 }
146 cleaned := path.Clean(p)
147 rel, err := relPath(skillRoot, cleaned)
148 if err != nil {
149 return err
150 }
151 content, err := fs.ReadFile(fsys, cleaned)
152 if err != nil {
153 return err
154 }
155 files[rel] = content
156 return nil
157 })
158 return files, err
159}
161// relPath returns full's path relative to root, rejecting anything that
162// would resolve outside root (e.g. "..", absolute paths, or sibling
163// directories). full must already be cleaned via path.Clean.
164func relPath(root, full string) (string, error) {
165 if full == root {
166 return "", fmt.Errorf("unexpected: file path %q equals skill root", full)
167 }
168 if !strings.HasPrefix(full, root+"/") {
169 return "", fmt.Errorf("path %q is not under skill root %q", full, root)
170 }
171 return full[len(root)+1:], nil
172}
Diagnostics8 git calls · 349 ms
CallStatusSizeTime0349 ms
discover200185 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=185 git.server.agent=git/2.56.g1891de4-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=185 git.pkt.payload.max=35
ls-refs20058 KiB · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=59849 git.response.cache=HIT git.response.duration_ms=2 git.protocol.version=2 git.pkt.frames=731 git.pkt.data=730 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=59849 git.pkt.payload.max=143 git.ls_refs.count=730 git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=4273 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=combine:blob:none+tree:2 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=1 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4273 git.pkt.payload.max=4173 git.sideband.band1.bytes=4173 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=11 git.pack.bytes=4173 git.fetch.wide.objects=11 git.fetch.wide.extra_bytes=3930 git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=32926 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=22 git.pkt.data=20 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=32926 git.pkt.payload.max=32046 git.sideband.band1.bytes=32046 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=80 git.pack.bytes=32046 git.pack.ofs_delta=36 git.pack.ref_delta=0 git.pack.chain.max=2 git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91 git.pack.full=44Open pack map
fetchtree:02001.8 KiB · hit1 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=1 git.response.bytes=1857 git.response.cache=HIT git.response.duration_ms=1 git.fetch.filter=tree:0 git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=1857 git.pkt.payload.max=1830 git.sideband.band1.bytes=1830 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=1830 git.pack.trailer=fb03183b7909876778f740d196d7516811003517Open pack map
fetchtree:0200370 B · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=370 git.response.cache=HIT git.response.duration_ms=4 git.fetch.filter=tree:0 git.fetch.wants=290ae7a62f76e23cbbd60697570f19b90ddcece6 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=370 git.pkt.payload.max=343 git.sideband.band1.bytes=343 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=343 git.pack.trailer=0795a26d2b25022c69da2ef2e68cfb92a77ef4bbOpen pack map
fetchtree:0200172 B · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=172 git.response.cache=HIT git.response.duration_ms=4 git.fetch.filter=tree:0 git.fetch.wants=1d776c45e9ce17714f94b096cf4965ac6cec85d5 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=172 git.pkt.payload.max=145 git.sideband.band1.bytes=145 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=145 git.pack.trailer=4366d9320a915cc228b00c299374927ba2a6e519Open pack map
fetch2002.0 KiB335 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=335 git.response.bytes=2080 git.response.cache=MISS git.response.duration_ms=335 git.fetch.wants=99babd3380f63bd5c8affa7736bdffab51242b95 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=2080 git.pkt.payload.max=2053 git.sideband.band1.bytes=2053 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://gitlab.com/gitlab-org/cli
- Ref
- refs/heads/main
- Commit
- 0dd7574dce9e385c5c30540e6c15657adc6bdce9
- cf-ray
- a5e30bfcad35ee28
- Request
- 81557c54…
- Protocol
- v2 · sha1
- Agent
- git/2.56.g1891de4-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format