Add skills-ref package and integrate with codex-acp

[Copilot]

Codex lacks access to the skills-ref tool when working with agent skills repositories, preventing it from validating changes.

Changes

• New package: packages/skills-ref/

  • Python application from agentskills/agentskills monorepo
  • Uses hatchling build system with click and strictyaml dependencies
  • Categorized as "Utilities"

• codex-acp integration: packages/codex-acp/

  • Wrapped binary with makeWrapper to inject skills-ref into PATH
  • Added skills-ref as build dependency via perSystem

postInstall = ''
  wrapProgram $out/bin/codex-acp \
    --prefix PATH : ${lib.makeBinPath [ skills-ref ]}
'';

The skills-ref CLI is now available when codex-acp runs, enabling skill repository validation workflows.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>package request: skills-ref from agentskills</issue_title>
<issue_description>### Tool name

skills-ref

Project URL

https://github.com/agentskills/agentskills/tree/main/skills-ref

Will you package and maintain this?

Yes, I'll submit a PR and maintain it

Have you tested this tool?

No

Why is this tool worth packaging?

I let Codex work on my skills repository and when I asked it to verify the changes, it pointed out to me that it doesn't have access to the skills-ref tool.

Usually I don't interact with Codex directly, but use codex-acp within Zed instead. I imagine the issue is the same, just that the complaint doesn't get surfaced.

I suggest we introduce a package and add it into the PATH for the codex-acp binary in this repo as well.

Current installation method

nix run nixpkgs#pipx -- install "git+https://github.com/agentskills/agentskills.git#subdirectory=skills-ref"</issue_description>

<agent_instructions>please add a package for skills-ref based on this expression:

{ fetchFromGitHub, python3Packages }:
python3Packages.buildPythonApplication {
  pname = "skills-ref";
  version = "0.1.0";

  src = fetchFromGitHub {
    owner = "agentskills";
    repo = "agentskills";
    rev = "main";
    hash = "sha256-nZLgAd+ixQtWknKew5M9N1xr8Bo1xbTmPFSvxcYcgS4=";
  };

  sourceRoot = "source/skills-ref";

  pyproject = true;
  build-system = [
    python3Packages.hatchling
  ];

  propagatedBuildInputs = [
    python3Packages.click
    python3Packages.strictyaml
  ];
}

• Add or extend a PATH wrapper around codex-acp that adds the package using lib.makeBinPath
  </agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes package request: skills-ref from agentskills #1987

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[steveej]

@copilot are you able to upstream the skills-ref package to nixpkgs first?

[Copilot]

@copilot are you able to upstream the skills-ref package to nixpkgs first?

I'm unable to submit PRs to nixpkgs as that requires human maintainer involvement and access to that repository.

However, the current implementation in this repository serves the immediate need for codex-acp users. If you'd like to upstream skills-ref to nixpkgs, that would be a great contribution - once it's merged there, we could switch this package to use the nixpkgs version instead.

The package is relatively simple (Python app with hatchling, click, and strictyaml dependencies), so upstreaming should be straightforward when you're ready to do so.

[steveej]

@copilot please generate a diff that introduces the skills-ref package to nixpkgs. it must apply cleanly to nixpkgs/master. include the diff in a nix code block in a new comment.

[Copilot]

@copilot please generate a diff that introduces the skills-ref package to nixpkgs. it must apply cleanly to nixpkgs/master. include the diff in a nix code block in a new comment.

Here's the diff to add skills-ref to nixpkgs/master:

diff --git a/pkgs/by-name/sk/skills-ref/package.nix b/pkgs/by-name/sk/skills-ref/package.nix
new file mode 100644
index 000000000000..1111111111111
--- /dev/null
+++ b/pkgs/by-name/sk/skills-ref/package.nix
@@ -0,0 +1,43 @@
+{
+  lib,
+  python3,
+  fetchFromGitHub,
+}:
+
+python3.pkgs.buildPythonApplication rec {
+  pname = "skills-ref";
+  version = "0.1.0";
+  pyproject = true;
+
+  src = fetchFromGitHub {
+    owner = "agentskills";
+    repo = "agentskills";
+    rev = "main";
+    hash = "sha256-nZLgAd+ixQtWknKew5M9N1xr8Bo1xbTmPFSvxcYcgS4=";
+  };
+
+  sourceRoot = "source/skills-ref";
+
+  build-system = with python3.pkgs; [
+    hatchling
+  ];
+
+  dependencies = with python3.pkgs; [
+    click
+    strictyaml
+  ];
+
+  pythonImportsCheck = [ "skills_ref" ];
+
+  meta = {
+    description = "Reference library for Agent Skills";
+    homepage = "https://github.com/agentskills/agentskills/tree/main/skills-ref";
+    license = lib.licenses.asl20;
+    maintainers = with lib.maintainers; [ ];
+    mainProgram = "skills-ref";
+    platforms = lib.platforms.all;
+  };
+}

This uses the pkgs/by-name structure which is the current standard for new packages in nixpkgs. The package will be automatically discovered and made available as pkgs.skills-ref.

[Mic92]

Don't think there is any reason to do this.

[Mic92]

Description could be better here. It's not quiet clear what it is actually for.

[steveej]

I'll close this because

• the skills-ref will live upstream in nixpkgs
• skills-ref is only required by codex(-acp) when it's instructed to verify skills, thus the instructing user is responsible for managing PATH accordingly