Files

Defame1297 430f46b8e8 docs: correct the claims this review found false

AGENTS.md told an offline agent to push with SKIP=apm-marketplace-check and
asserted that hook was "the only one whose failure mode is 'no network'".
Running all 12 pre-push hooks under a network namespace shows two fail, for
one shared cause: apm-pack-check-clean resolves the same remote entry. An
exact pin does not remove the ls-remote, so both hooks are named now.

AGENTS.md also said everything in a plugin root except .apm/ is generated.
Plugin roots carry hand-authored README.md, docs/, bin/, sources.md and
.mcp.json, so an agent would hunt for an .apm/ source that does not exist or
refuse the edit. The rule is positional: immunity belongs to the plugin root,
and anything inside a mirrored directory is still rm -rf'd.

ADR-0017 said apm strips a hooks field. The real loop is (agents, skills,
commands, instructions) -- hooks absent, instructions never mentioned -- and
it can never fire, because synthesize_plugin_json_from_apm_yml only emits the
eight identity fields. The decision stands; the mechanism was overstated. Its
mcpServers amendment is rewritten for the pointer payload and now records the
real reason: inlining bypassed apm's credential sanitizer.

ADR-0015's owner.email and version-pin passages are corrected against the apm
source, and ADR-0016 gains the disallowedTools amendment. agent-audit's
allowlist is data, so it gains disallowedTools too -- the ADR and the
validator that enforces it had come apart.

architecture.md described a root CLAUDE.md that imports two files (it imports
one, plus an RTK block) and pointed at an ADR index that does not exist.
Seven skill READMEs listed tests/ files the mirror strips, promising installed
users files their install lacks; those rows are marked source-only, with the
depth-4 template tests explicitly called out as surviving. And
plugins/kyberforge/hooks/README.md, deleted during the conversion and
preserved nowhere, is restored to a path the mirror does not own -- verified
by running a sync against a scratch copy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X7GvKuJfy2WrdBmUttV4DT

2026-08-14 11:04:56 +00:00

3.7 KiB

Raw Blame History

skill-author

Author and refine skills conforming to the agentskills.io specification — create new skills from scratch or apply improvement signals to existing ones.

What it does

Routes to one of two flows based on context: if no skill directory exists at the target path, it scaffolds the directory from annotated templates, fills in SKILL.md and supporting files, and validates the result. If an existing skill directory and improvement signals are both present, it groups those signals by root cause and applies targeted edits, then re-validates. In both flows, bumps the skill's metadata.version when present (minor for create, patch for improve).

Before you start

Run /grill-me to resolve design decisions before creating a new skill
Collect domain research, examples, and constraints
Know the skill name (kebab-case) and destination path

Placement

scripts/new-skill.sh resolves the mode automatically by walking up from the given path — see SKILL.md Step 1 for the full algorithm.

Mode	Path	Chosen when
Standalone	`<path>/<name>/`	No `apm.yml` with a top-level `type:` field is found walking up from `<path>`, before hitting `.git` or the filesystem root
Package (APM)	`<package-root>/.apm/skills/<name>/`	A type-bearing `apm.yml` is found at or above `<path>` — `<path>` just needs to be somewhere inside the package

If the destination resolves inside an APM package, read references/deployment-modes.md — self-containment rules apply to apm compile output the same way they applied to plugin cache isolation.

Usage

/skill-author

Files

File	Purpose
`README.md`	Human-readable overview of the skill and its files
`SKILL.md`	Skill instructions for agents
`scripts/new-skill.sh`	Walks up from the given path to resolve package vs standalone mode, then copies annotated templates to the resolved destination
`references/deployment-modes.md`	APM package vs standalone differences and self-containment/cache-isolation rules (loaded on demand)
`references/scripts.md`	Package runners, inline dependency patterns, and full script contract (loaded on demand)
`references/sources.md`	Upstream research sources and which skill files each contributed to
`assets/templates/SKILL.md`	Annotated SKILL.md template
`assets/templates/README.md`	Annotated README template for the new skill
`assets/templates/scripts/README.md`	Placeholder for bundled scripts
`assets/templates/references/README.md`	Placeholder for reference docs
`assets/templates/references/sources.md`	Sources provenance template for new skills
`assets/templates/assets/README.md`	Placeholder for static assets
`assets/templates/tests/README.md`	Placeholder for test files
`tests/new-skill.bats`	(source-only) Bats test suite for `scripts/new-skill.sh`
`tests/README.md`	(source-only) Setup instructions for bats-support and bats-assert test dependencies

Rows marked (source-only) exist in the authoring source (.apm/skills/skill-author/) but are not present in an installed plugin: scripts/sync-plugin-content.sh strips <category>/<name>/tests when it generates the flat mirror, because these are dev-time fixtures no plugin host needs to discover (ADR-0017). Run them from a repo checkout, not from an install. The assets/templates/tests/README.md row above is not source-only — the exclusion is depth-scoped to <category>/<name>/tests, so the scaffolding template tree ships intact, which scripts/new-skill.sh depends on at runtime.

Spec reference

agentskills.io specification

3.7 KiB Raw Blame History