---
title: "Author a Skill for your npm package · skilld"
description: "Draft a Skill from your public API, include it in your npm package, and check the tarball before publishing."
canonical_url: "https://skilld.dev/learn/author-npm-package-skills"
last_updated: "2026-08-20T06:40:33.845Z"
meta:
  "og:description": "Draft a Skill from your public API, include it in your npm package, and check the tarball before publishing."
  "og:image": "https://skilld.dev/_og/d/a_~c2tpbGxkLCBhZ2VudCBza2lsbHMgd3JpdHRlbiBieSByZWFsIG1haW50YWluZXJz%2Cc_Page.takumi%2Cdescription_~Q3VyYXRlZCBhZ2VudCBza2lsbHMgYnkgaHVtYW5zLCB3cml0dGVuIGJ5IHJlYWwgbWFpbnRhaW5lcnMgaW4gdGhlaXIgb3duIEdpdEh1YiByZXBvcw%2Cp_Ii9sZWFybi9hdXRob3ItbnBtLXBhY2thZ2Utc2tpbGxzIg%2Cs_tdopPWUPi7AT18To.png"
  "og:image:alt": "skilld, agent skills written by real maintainers"
  "og:image:height": "600"
  "og:image:type": image/png
  "og:image:width": "1200"
  "og:title": "Author a Skill for your npm package"
  "twitter:image": "https://skilld.dev/_og/d/a_~c2tpbGxkLCBhZ2VudCBza2lsbHMgd3JpdHRlbiBieSByZWFsIG1haW50YWluZXJz%2Cc_Page.takumi%2Cdescription_~Q3VyYXRlZCBhZ2VudCBza2lsbHMgYnkgaHVtYW5zLCB3cml0dGVuIGJ5IHJlYWwgbWFpbnRhaW5lcnMgaW4gdGhlaXIgb3duIEdpdEh1YiByZXBvcw%2Cp_Ii9sZWFybi9hdXRob3ItbnBtLXBhY2thZ2Utc2tpbGxzIg%2Cs_tdopPWUPi7AT18To.png"
  "twitter:image:alt": "skilld, agent skills written by real maintainers"
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

# **Author a Skill for your npm package**

Draft a Skill from your public API, include it in your npm package, and check the tarball before publishing.

Authoring guide

## 1. Draft your Skill

npm

[Choose your package](https://skilld.dev/make-skill?ecosystem=npm)

Open your agent in the package repository. Give it these instructions to draft your Skill.

[Read the authoring Skill](https://raw.githubusercontent.com/skilld-dev/skilld/main/skills/generate-package-skill/SKILL.md)

Read https://raw.githubusercontent.com/skilld-dev/skilld/main/skills/generate-package-skill/SKILL.md. Draft a Skill for the package I maintain, published through npm, using this repository. Read package.json, the public API, and the current official documentation. Save each Skill in skills/\<name>/SKILL.md beside package.json, so pnpm can discover it. Include the Skill and its linked files in the published tarball. Read https://pnpm.io/agent-skills for pnpm approval and linking. Show the draft for review before replacing existing Skills.

Point your agent at the directory containing your package's `**package.json**`. For a monorepo, use the individual package directory. Ask it to save the draft in `**skills/your-skill/SKILL.md**`. Keep `**skills/**` beside that package's `**package.json**`. [**pnpm 12.11 and newer**](https://pnpm.io/agent-skills) discover Skills one level deep at `**skills/<name>/SKILL.md**`.

Describe the tasks your package handles and the mistakes agents should avoid. Check public exports, TypeScript types, supported runtimes, and version limits. Use current examples from your own documentation.

## 2. Review the draft

Run each example against the package version you plan to release. Use [**the cross-Agent selection and task checks**](https://skilld.dev/learn/create-agent-skills#check-selection-and-task-completion-separately) before publishing the Skill. Remove generic advice and unsupported claims. Keep detailed material in `**references/**` and link it from `**SKILL.md**`. Use the [**authoring Skill's quality checks**](https://github.com/skilld-dev/skilld/tree/main/skills/generate-package-skill) before committing.

## 3. Include the Skill in your package

If `**package.json**` has a `**files**` list, add `**skills**` to the existing entries. Keep the entries for your built code and other release files. Check `**.npmignore**` rules that could exclude the Skill or its references. The [**npm package.json reference**](https://docs.npmjs.com/cli/v11/configuring-npm/package-json/#files) explains file inclusion.

From the package directory, inspect the release file list:

```bash
npm pack --dry-run
```

Confirm it includes `**skills/your-skill/SKILL.md**` and every linked local file. This command checks the [**npm**](https://npmjs.com) tarball, regardless of which package manager you use for development. See the [**npm pack reference**](https://docs.npmjs.com/cli/v11/commands/npm-pack).

## 4. Publish and share

Commit the reviewed Skill and publish through your normal release process. Link to its repository directory from your package README. Keep the Skill link visible so developers can choose how to use it.

Developers using pnpm 12.11 or newer can approve Skills from direct dependencies with `**pnpm approve**`. pnpm records the choice in `**pnpm-workspace.yaml**`:

```yaml
permissions:
  your-package:
    skills: true
```

Replace `**your-package**` with the published package name, including its scope. Merge this entry into existing permissions. Approval covers every Skill in the package and every later version. Ask developers to read the Skills before approving.

pnpm links approved Skills into existing Agent directories at the workspace root. Developers can choose directories with `**skills.dirs**` in `**pnpm-workspace.yaml**`:

```yaml
skills:
  dirs:
    - .agents/skills
```

Merge this setting into the existing workspace file, then run `**pnpm install**`. For `**your-package**`, the example Skill appears at `**.agents/skills/pnpm-your-package-your-skill/SKILL.md**`. A scoped package replaces `**/**` with `**+**` in the link name. pnpm owns these links and removes them when the package or approval disappears. Global installs, `**pnpm dlx**`, and `**pnpm deploy**` do not link Skills. See [**pnpm's approval and linking rules**](https://pnpm.io/agent-skills).

When your API changes, review the Skill alongside your package documentation.

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://skilld.dev/#website","@type":"WebSite","description":"Curated agent skills by humans, written by real maintainers in their own GitHub repos","name":"skilld","url":"https://skilld.dev/"},{"@id":"https://skilld.dev/learn/author-npm-package-skills#webpage","@type":"WebPage","description":"Draft a Skill from your public API, include it in your npm package, and check the tarball before publishing.","name":"Author a Skill for your npm package","url":"https://skilld.dev/learn/author-npm-package-skills","isPartOf":{"@id":"https://skilld.dev/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://skilld.dev/learn/author-npm-package-skills"]}]}]}
```