package-skill

# Package Agent Skill for Dockyard This skill helps you package agent skills for distribution via Dockyard skill artifacts (OCI artifacts published to `ghcr.io/stacklok/dockyard/skills/{name}`). Unlike MCP servers — which Dockyard builds into container images from an npm/PyPI/Go package — skills are repackaged directly from a pinned commit in the upstream skill's git repository. There's no build step; `dockhand` clones the repo, validates `SKILL.md`, and repackages that directory as-is. ## When to Use This Skill Use this skill when: - Adding a new agent skill to Dockyard - Creating a `skills/{name}/spec.yaml` configuration file - Vendoring one or more skills from a third-party repository - The user mentions "package skill", "add skill", "skills spec.yaml", or asks to package skills from a named GitHub org/repo ## Prerequisites - The skill's `SKILL.md` must exist in a public git repository, reachable over HTTPS - `go build -o build/dockhand ./cmd/dockhand` (or `task build-setup`) for local validate/build - `task scan-skill-setup` (installs `cisco-ai-skill-scanner` via `uv`) for local scanning ## Workflow ### Step 1: Discover the skill(s) If packaging from a repo the user names, clone it shallow and enumerate candidate `SKILL.md` files: ```bash git clone --depth 1 https://github.com/{org}/{repo} /tmp/{repo} find /tmp/{repo} -iname SKILL.md ``` Treat the results as candidates, not an automatic package list: exclude test fixtures, examples, and templates that are not intended for end users. For each real skill, read its YAML frontmatter (`name`, `description`, and any `license`/`version` fields). The upstream description is the source of truth for `metadata.description`. #### Verify redistribution rights Before creating any specs, find an explicit license that covers the skill content. Check the skill directory and repository root for `LICENSE`/`COPYING` files and inspect any SPDX-style `license:` value in `SKILL.md` frontmatter. The license must grant the rights needed to copy, modify, and redistribute the skill in a public OCI artifact. Public source is not the same as open source. A repository with no license is not eligible for packaging unless the copyright holder separately grants the necessary redistribution rights. Likewise, a link to product, API, developer, or website terms is not sufficient unless those terms explicitly license the repository content for redistribution. If the license is missing, ambiguous, or non-redistributable, stop and surface the issue to the user rather than creating specs. Record the license and where it was found in the PR description. skill-scanner reports `MANIFEST_MISSING_LICENSE` when the license is at the repository root rather than in `SKILL.md`; that rule is allowlisted globally because this license check replaces it, so don't add a per-skill entry. Get the pinned commit SHA once, up front, and reuse it for every skill from that repo: ```bash git -C /tmp/{repo} rev-parse HEAD ``` ### Step 2: Decide names — check for collisions `skills/` is a single flat namespace shared by 150+ skills from many upstream sources. Before naming anything: ```bash ls skills/ | grep -x '{candidate-name}' ``` - If the skill's own upstream name is already specific and unlikely to collide (`claude-api`, `gh-stack`), use it as-is. - If the repo ships **multiple** skills whose names are generic on their own (e.g. `provider-docs`, `windows-builder`, `push-to-registry`), prefix **all** of them with a short vendor tag: `hashicorp-provider-docs`, `dd-apm` (Datadog), `hf-cli` (Hugging Face). - Prefer a single flat vendor prefix over splitting by upstream sub-project (e.g. `hashicorp-` alone, not separate `hashicorp-terraform-`/`hashicorp-packer-` prefixes) — splitting produces stutter whenever a skill's own name already contains the sub-project name (`hashicorp-terraform-terraform-test` reads worse than `hashicorp-terraform-test`). - If there's any ambiguity in naming (flat vendor prefix vs. per-subproject, or no prefix at all), **ask the user** before creating two dozen directories — renaming later means re-running the whole scan/allowlist pass. ### Step 3: Create spec.yaml One directory per skill: `skills/{name}/spec.yaml`. ```yaml # {Skill Name} Skill # Source: {source-repository-url} # Will publish as: ghcr.io/stacklok/dockyard/skills/{name}:0.1.0 metadata: name: {name} description: "{copy verbatim from upstream SKILL.md frontmatter description}" spec: repository: "{https-git-clone-url}" ref: "{commit-sha}" # {branch} as of {date} — pin an exact commit, never a branch path: "{path-to-skill-dir}" # omit entirely if SKILL.md is at repo root version: "0.1.0" # ALWAYS 0.1.0 for a new skill — see Step 4 provenance: repository_uri: "{https-git-clone-url}" repository_ref: "refs/heads/{branch}" # Renovate follows this branch ``` Long `description` values often need YAML block scalars (`>-` or a quoted multi-line string) — let a YAML dumper handle escaping rather than hand- wrapping; malformed quoting is the most common review-round-trip bug here. ### Step 4: Version — always start at 0.1.0 Do **not** copy an upstream release tag (e.g. a repo-wide `v1.0.0`) into `spec.version`, even if one exists. Dockyard owns semver for every vendored skill independently of upstream (see `docs/skill-versioning.md`) specifically because: - Most upstream skill repos don't tag individual skills at all. - Even when a repo does cut a release, it's typically a whole-repo tag that doesn't map to any single skill's actual changes — and several individual `SKILL.md` frontmatter blocks often carry their own, much lower, per-skill `version` (e.g. `0.0.1`, `0.1.0`) that would contradict a `1.0.0` Dockyard tag anyway. Every new skill starts at `0.1.0`. If this comes up with the user, it's worth surfacing as a quick recommendation rather than silently picking one — but the answer is almost always 0.1.0. ### Step 5: Validate ```bash build/dockhand validate-skill --config skills/{name}/spec.yaml ``` Fix any error before moving on — this clones the repo and actually checks `SKILL.md` exists at the given path. ### Step 6: Scan and triage findings ```bash task scan-skill-setup # once per machine task scan-skill -- skills/{name} ``` This is the expensive, judgment-heavy step. Read `scripts/skill-scan/README.md` if you haven't already. What to expect: - **Warnings** (below the `HIGH` block threshold) don't fail the task. You can leave them; `MEDIUM` ones are listed in the PR scan comment for a reviewer to check. - **Blocking findings** (`HIGH`+, unallowlisted) fail the task and must be triaged one by one. For each blocking finding, look at its `file_path`/`line_number`/`message` and decide: genuine issue, or false positive? Skill docs are prose- and example-heavy, so the overwhelming majority are false positives from pattern/keyword rules matching on things like: - Shell variable expansion (`${TOKEN}`, `$HOME`) in documented setup commands - Documented, vendor-official install one-liners (`curl -L .../release`, `sudo apt-get install`, an official Chocolatey/PowerShell bootstrap) - Example IP addresses, placeholder credentials (`CLIENT_SECRET="your-secret"`), or attribute names like `password` in schema/code examples - Words like "exfil", "override", "skip", "kill", "root" appearing in ordinary explanatory prose, not as an executable instruction Add each as a `security.allowed_issues` entry, matching by `rule_id` (exact — prefer this) or `category` (broader, only when many distinct rule_ids share one clear rationale). **Every reason must cite the specific matched text and its file:line**, and explain concretely why it isn't a threat — not just "false positive": ```yaml security: allowed_issues: - rule_id: PG_PII_CREDENTIAL_HARVESTING reason: "FP: matched advice to store credentials in a dedicated \`~/.mcp-env\` file (SKILL.md:213). The skill tells users where to keep their own credentials; it never asks the user for them." ``` When packaging many skills from the same repo, findings cluster heavily by `rule_id` — collect all blocking findings across the batch first (group by skill + rule_id), write one templated-but-specific reason per rule_id, then customize per skill using that skill's actual matched text. Don't reuse a reason verbatim across skills without checking the cited location actually matches what's in *that* skill — genuinely different constructs can share a rule_id (e.g. an `iex (...)` PowerShell bootstrap vs. a `sudo apt-get install` line both trip the same "documented install command" rule but need different citations). Never set `security.insecure_ignore: true` to bypass this — it disables the gate rather than documenting the finding. Re-run `task scan-skill -- skills/{name}` until it exits clean. Repeat for every skill in the batch. ### Step 7: Build (smoke test) ```bash build/dockhand build-skill --config skills/{name}/spec.yaml ``` No `--push` needed locally — this just proves the artifact packages successfully end to end. Doing this for at least one representative skill in a batch is enough; running it for all of them is optional but cheap. ### Step 8: Commit ```bash git add skills/{name}/spec.yaml git commit -s -m "Add {name} skill Package {name} from {upstream-repo} at {commit-sha}. Source: {upstream-repo-url}" ``` Use `git commit -s` — DCO Signed-off-by is required (see `CONTRIBUTING.md`). For a batch of skills from one repo, one commit covering all of them is fine. ## Common Issues | Issue | Solution | |-------|----------| | `validate-skill` fails: SKILL.md not found | Double check `spec.path` — it's relative to the repo root, not to `skills/{name}/` | | `scan-skill` times out on a large batch | Run it per-skill in a loop rather than one long-running batch command; each clone+scan takes 5-15s | | Same `rule_id` fires for unrelated reasons across skills | Verify the actual matched text before reusing a reason — don't copy-paste blind | | Version bump CI failure after editing `spec.ref` later | Run `go run ./cmd/skillversionbump --base origin/main --write` — see `docs/skill-versioning.md` | | Tempted to set `insecure_ignore: true` | Don't. Triage the finding instead, or ask the user if it's a genuine risk to accept explicitly with a reason | ## See Also - [docs/adding-skills.md](../../../docs/adding-skills.md) — Complete contribution guide - [docs/skill-versioning.md](../../../docs/skill-versioning.md) — Why version always starts at 0.1.0 - [docs/security.md](../../../docs/security.md) — Security scanning and attestation model - `scripts/skill-scan/README.md` — Scanner wrapper scripts and allowlist mechanics - [internal/skills/spec.go](../../../internal/skills/spec.go) — The actual validated spec.yaml fields - [references/SPEC-YAML-REFERENCE.md](references/SPEC-YAML-REFERENCE.md) — Full spec.yaml field reference