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.3 KiB

Raw Blame History

agent-author

Creates and improves agent definition files for Claude Code and GitHub Copilot CLI.

What it does

Scaffolds and fills in agent definition files at plugin/APM, project, or user scope. Project and user scope always generate a Claude Code + Copilot CLI file pair (.md + .agent.md) in one pass. Plugin/APM scope generates a single vendor-neutral .apm/agents/<name>.agent.md file instead — no separate Claude Code / Copilot split, since apm compile has no per-target field integrator (see ADR-0016). Also applies improvement signals — grill output, inline feedback, session context — to existing agent files. Bumps the version after every change: the resolved package's apm.yml at plugin/APM scope (minor for new agents, patch for improvements); project/user scope has no manifest to bump.

Before you start

Have ready: the agent's name (kebab-case), the root directory (plugin root, project root, or ~), a one-sentence purpose, and the triggering condition (when should the runtime delegate to this agent?).

Usage

/agent-author

Manual scaffold (human workflow):

bash scripts/new-agent.sh <agent-name> <root>

# Examples:
bash scripts/new-agent.sh code-reviewer packages/my-package/   # plugin/APM scope if packages/my-package/apm.yml has a type: field
bash scripts/new-agent.sh deploy-assistant .
bash scripts/new-agent.sh security-reviewer ~

Files

File	Purpose
`SKILL.md`	Skill instructions for agents
`scripts/new-agent.sh`	Scaffolds agent definition file(s) from templates — a single `.apm/agents/<name>.agent.md` at plugin/APM scope, or a Claude Code + Copilot CLI pair at project/user scope
`references/deployment-modes.md`	Plugin/APM vs project vs user scope: restrictions, scoped identifiers, path conventions
`references/scripts.md`	Conventions for new-agent.sh and any future scripts: contract, template variables, file placement, error messages
`references/sources.md`	Research provenance — sources that informed this skill
`assets/templates/claude-code.md`	Annotated Claude Code agent definition template (project/user scope)
`assets/templates/copilot.agent.md.template`	Annotated Copilot CLI agent definition template (project/user scope)
`assets/templates/apm-agent.md`	Annotated vendor-neutral APM agent definition template (plugin/APM scope)
`tests/new-agent.bats`	(source-only) bats tests for `scripts/new-agent.sh`
`assets/README.md`	Directory meta-documentation for assets/
`references/README.md`	Directory meta-documentation for references/
`scripts/README.md`	Directory meta-documentation for scripts/
`tests/README.md`	(source-only) bats dependency instructions and run command

Rows marked (source-only) exist in the authoring source (.apm/skills/agent-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/ rows above are unaffected — the exclusion is depth-scoped to <category>/<name>/tests, so template trees that themselves contain a tests/ directory ship intact.

3.3 KiB Raw Blame History