Skip to content

docs: document npm as a distribution channel #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CybotTM merged 2 commits into from
May 2, 2026
Merged

docs: document npm as a distribution channel #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0fba45e
docs: document npm as a distribution channel
CybotTM May 2, 2026
4ca5d19
fix(docs): correct composer version assertion and LICENSE allowlist (…
CybotTM May 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,13 @@ skills/github-project/
## Distribution Channels

- **Composer**: `netresearch/github-project-skill` via `composer.json` (requires `composer-agent-skill-plugin`)
- **npm**: `github:netresearch/github-project-skill` via `package.json` (requires `@netresearch/agent-skill-coordinator`, which discovers the skill in `node_modules` and registers it in `AGENTS.md` via a `postinstall` hook)
- **Claude Code plugin**: `.claude-plugin/plugin.json` for marketplace distribution
- **npx / skills.sh**: Direct install via `npx skills add`
- **Git clone / release download**: Manual installation

When making changes to release or distribution logic, all five channels must be considered. The npm channel ships from a `package.json` allowlist (`files: ["skills/github-project/", "LICENSE-MIT", "LICENSE-CC-BY-SA-4.0", "README.md"]`) — anything outside that allowlist is invisible to npm consumers.

## Key Design Decisions

- **Platform-only scope**: This skill handles GitHub platform features. CI/CD content, language tooling, and security scanning are delegated to dedicated skills.
Expand Down
5 changes: 3 additions & 2 deletions skills/github-project/references/multi-repo-operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,8 @@ The canonical order is: **version-bump PR merged → tag pushed**, never the rev

Before touching any repo, validate:

- `plugin.json.version` / `composer.json.version` / `package.json.version` parity against each other
- `plugin.json.version` is present (authoritative) and `composer.json` has **no** `version` field (Packagist derives the version from git tags); if `SKILL.md` frontmatter carries a `metadata.version`, it must match `plugin.json.version`
- For repos that also ship via npm: `package.json.version` is either the placeholder `0.0.0-source` (publish-time-rewritten by the Release workflow) **or** matches `plugin.json` (for coordinator-style packages, e.g. `@netresearch/agent-skill-coordinator`). Mixing the two within one repo is the bug pattern to look for.
- Current git tag on default branch is not already the target version
- CI on default branch is green
- No pending version-bump PR already open
Expand All @@ -116,7 +117,7 @@ skills/skill-repo/scripts/check-version-parity.sh # parity only
skills/skill-repo/scripts/check-version-parity.sh v1.2.4 # also require tag parity
```

That script handles the Netresearch conventions (`plugin.json` has the authoritative version, `composer.json` must not have one, `SKILL.md` `metadata.version` in frontmatter matches `plugin.json`). Don't copy the snippet below inline — it was a sketch for illustration; the real script handles empty-arg mode, missing files, glob-empty iteration, and the quoted-or-unquoted frontmatter form. Call the shipped script.
That script handles the Netresearch conventions (`plugin.json` has the authoritative version, `composer.json` must not have one, `SKILL.md` `metadata.version` in frontmatter matches `plugin.json`, and `package.json.version` is either `0.0.0-source` for git-installed skill packages or matches `plugin.json` for npm-published coordinator-style packages). Don't copy the snippet below inline — it was a sketch for illustration; the real script handles empty-arg mode, missing files, glob-empty iteration, and the quoted-or-unquoted frontmatter form. Call the shipped script.

```bash
# Illustrative only — for non-skill repos, adapt the shape but handle empties
Expand Down
Loading