Is your feature request related to a problem? Please describe.
APM defines the primitive types but doesn't ship guidance on how to author a good package. New authors keep rediscovering the same rules: instruction vs skill, applyTo: scope, trigger phrasing, what to leave out, version policy, layout. The result is uneven quality across the ecosystem.
The cleanest fix is the one APM is already optimised for: an APM package whose rules auto-activate exactly when an author is editing an APM primitive.
Describe the solution you'd like
A first-party apm-authoring package distributed from this repo:
- instructions file scoped to
apm.yml, SKILL.md, *.instructions.md, *.prompt.md, *.agent.md, AGENTS.md, CLAUDE.md;
- one
SKILL.md covering package layout, the instruction-vs-skill decision, frontmatter rules, version policy, and common pitfalls.
Installed as a devDependency, it would steer any APM-aware agent the moment someone opens a SKILL.md or apm.yml — no separate docs trip needed.
We have a working version we'd be glad to upstream as a starting point:
https://github.com/Netcracker/qubership-ai-packages/tree/main/agent-packages/apm-authoring
Describe alternatives you've considered
- Each org maintains its own authoring skill (current state — causes ecosystem drift).
- Static authoring docs in the README — doesn't activate at the moment of authoring, which is APM's whole value proposition.
- An
apm lint validator — useful and complementary, but only catches schema-level mistakes, not "this should be a skill, not an instruction" decisions.
Additional context
Happy to contribute the package itself, a vendor-neutral rewrite, or just the conventions list — whatever fits the repo's direction.
Also happy to discuss whether the right home is in-tree, a sibling microsoft/apm-authoring repo, or a community-maintained package.
Is your feature request related to a problem? Please describe.
APM defines the primitive types but doesn't ship guidance on how to author a good package. New authors keep rediscovering the same rules: instruction vs skill,
applyTo:scope, trigger phrasing, what to leave out, version policy, layout. The result is uneven quality across the ecosystem.The cleanest fix is the one APM is already optimised for: an APM package whose rules auto-activate exactly when an author is editing an APM primitive.
Describe the solution you'd like
A first-party
apm-authoringpackage distributed from this repo:apm.yml,SKILL.md,*.instructions.md,*.prompt.md,*.agent.md,AGENTS.md,CLAUDE.md;SKILL.mdcovering package layout, the instruction-vs-skill decision, frontmatter rules, version policy, and common pitfalls.Installed as a
devDependency, it would steer any APM-aware agent the moment someone opens aSKILL.mdorapm.yml— no separate docs trip needed.We have a working version we'd be glad to upstream as a starting point:
https://github.com/Netcracker/qubership-ai-packages/tree/main/agent-packages/apm-authoring
Describe alternatives you've considered
apm lintvalidator — useful and complementary, but only catches schema-level mistakes, not "this should be a skill, not an instruction" decisions.Additional context
Happy to contribute the package itself, a vendor-neutral rewrite, or just the conventions list — whatever fits the repo's direction.
Also happy to discuss whether the right home is in-tree, a sibling
microsoft/apm-authoringrepo, or a community-maintained package.