Understand the package root

The selected directory is the package root. Authoring reads root plugin.json and its standard components. It does not search parents for a project or fall back to a native client's hidden manifest.

Minimal and combined layouts

A Skill-only package:

review-helper/
  plugin.json
  skills/
    review-docs/
      SKILL.md

A remote hybrid package:

research-helper/
  plugin.json
  mcp.json
  skills/
    research-guide/
      SKILL.md

A stdio package also carries its runtime source and dependency manifests. Those files are needed for later execution, but their presence does not cause the authoring reader to execute anything.

Give each file a clear responsibility

File or directory	Responsibility
plugin.json	Standard package identity and metadata.
mcp.json	MCP server configuration when the package supplies tools.
skills/<name>/SKILL.md	One immediate Skill's identity, description, and instructions.
README.md	Intended use, prerequisites, validation, and remaining limits.
package.json, package-lock.json, src/server.mjs	Node stdio scaffold inputs for separate runtime work.
LICENSE	Explicit selected license, when supplied during init.

The scaffold starts the manifest version at 0.1.0. That is your new package's metadata, not the authoring executable's release version. Keep the distinction when reporting versions to users.

Identity and optional metadata

Use explicit --name and --description in repeatable init instructions. The public contract can derive a name from a bare destination name and supplies a deterministic default description, but paths such as ./review-helper should carry an explicit name. These tutorials supply both to avoid accidental identity.

For templates containing a Skill, --skill-name defaults to the package name when omitted. Choose it explicitly if the Skill needs a different identity. Skill names are never silently normalized.

Optional --author-name supplies an explicit author. No author is inferred from Git or the environment. License generation supports explicit MIT or ISC choices and requires both --copyright-holder and a four-digit --copyright-year. There is no default license selection.

Select the root consistently

agentplugins author validate ./research-helper
agentplugins author inspect ./research-helper
agentplugins author test ./research-helper

All three select the same package root. Passing ./research-helper/skills would select the wrong directory. The optional path on read commands defaults only to the current directory, not a discovered parent.

Standard conformance and filesystem safety are separate concerns. A schema-valid identity can still be unsuitable for a host path, and a readable manifest alone can leave required component evidence incomplete. Use the full report.

Continue with static checks, then handoff.