From 9cfe58ccb6fac8352a2c1bf121702f47c38ac185 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 26 Jan 2026 18:06:46 -0500 Subject: [PATCH 1/8] Propose Agent Skills --- text/0000-ai-agent-skills.md | 110 +++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 text/0000-ai-agent-skills.md diff --git a/text/0000-ai-agent-skills.md b/text/0000-ai-agent-skills.md new file mode 100644 index 0000000000..b7ff9b64ae --- /dev/null +++ b/text/0000-ai-agent-skills.md @@ -0,0 +1,110 @@ +--- +stage: accepted +start-date: 2026-01-26T00:00:00.000Z +release-date: # In format YYYY-MM-DDT00:00:00.000Z +release-versions: +teams: + - learning + - tooling +prs: + accepted: # Fill this in with the URL for the Proposal RFC PR +project-link: +suite: +--- + + + +# Adopt Agent Skills for Ember Tooling + +## Summary + +Adopt the Agent Skills repository (https://github.com/NullVoxPopuli/agent-skills) under the `ember-tooling` GitHub organization and treat it as the canonical home for Ember-focused “skills” for AI coding agents. + +In practice, this gives the community a stable, reviewable way to package Ember best practices and lightweight automation for agents, similar in spirit to how we treat lint rules and guides as shared infrastructure. + +## Motivation + +AI assistants are already part of day-to-day development. The ecosystem needs a way to: + +- Share Ember-specific guidance in a format agents can reliably consume +- Keep that guidance updated through normal OSS workflows (PR review, changelog, release cadence) +- Make it easy for teams to standardize how agents review Ember code (performance, accessibility, conventions) + +The `agent-skills` project provides an existing, interoperable format (agentskills.io) for packaging agent instructions and helper scripts. + +The fork at https://github.com/NullVoxPopuli/agent-skills already includes Ember-focused content (notably an “ember-best-practices” skill) and supporting build/validation tooling. + +## Detailed design + +### What is an “Agent Skill”? + +An Agent Skill is a small, versioned bundle of: + +- Agent-facing instructions (for example, how to review code or how to run a task) +- Optional helper scripts for automation +- Optional references + +The intention is that an agent can automatically apply a skill when it detects the task is relevant (e.g. “Review this Ember component for performance issues”). + +### Proposal + +1. Transfer or mirror the repository to `ember-tooling/agent-skills`. +2. Treat Ember-related skills in that repo as recommended defaults for Ember workflows. +3. Establish a lightweight review and release process so changes to skills are: + - auditable (PR review) + - testable (CI/validation) + - versioned (tags/releases) + +This RFC does not require any one editor or AI provider. The point is to maintain shared content in a vendor-neutral format. + +### Scope (initial) + +Start with the Ember-focused skill(s) already present in the fork, especially “ember-best-practices” (performance + accessibility oriented), and iterate from there. + +Non-Ember skills that happen to live in the repo today can remain if they are useful for web development in general, but the adoption goal is to ensure Ember-centric guidance is first-class. + +### Installation / usage + +Agent Skills are installed from a repository reference (for example via tooling that supports []`npx add-skill …`](https://github.com/vercel-labs/skills?tab=readme-ov-file#skills)). Once installed, compatible agents can auto-apply skills when prompted. + +We should document the “happy path” using the `ember-tooling` repo location once adopted. + +## How we teach this + +- Add a short Guides section: “AI-assisted development: Skills” explaining what skills are, when to use them, and how to install them. +- Provide 2–3 concrete examples: + - “Review this Ember route for data fetching issues” + - “Audit this template for accessibility regressions” + - “Suggest improvements for bundle size / build output” +- Cross-link from the `ember-mcp` recommendation: MCP provides data/tools; skills provide opinionated workflows. + +## Drawbacks + +- Maintenance burden: best practices evolve, and a “recommended” skill set must keep pace. +- Risk of over-prescription: skills can encode opinions; we’ll need clear language about what’s “recommended” vs “optional.” +- Safety: skills may include scripts; maintainers should be conservative about automation and emphasize review of actions. + +## Alternatives + +- Keep everything ad-hoc in blog posts / gists (hard to discover, not versioned, not enforceable). +- Rely solely on generic AI models plus docs (agents still miss context, and there’s no shared review surface). +- Build Ember-specific integrations per editor/provider (more work, less portable). + +## Unresolved questions + +- Governance: which group owns reviews and releases (Tooling team, Learning team, or shared working group)? +- Release model: tags only, GitHub releases, or also published packages? +- Policy: what skills qualify as “recommended” (and how do we deprecate or supersede skills)? +- Security posture: what constraints do we place on including scripts (network access, destructive commands, sandboxing guidance)? From de9d34a77c286b1c31265592f7399d60e0db1997 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 26 Jan 2026 18:08:09 -0500 Subject: [PATCH 2/8] Update meta --- text/{0000-ai-agent-skills.md => 1165-ai-agent-skills.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename text/{0000-ai-agent-skills.md => 1165-ai-agent-skills.md} (98%) diff --git a/text/0000-ai-agent-skills.md b/text/1165-ai-agent-skills.md similarity index 98% rename from text/0000-ai-agent-skills.md rename to text/1165-ai-agent-skills.md index b7ff9b64ae..49b9053b47 100644 --- a/text/0000-ai-agent-skills.md +++ b/text/1165-ai-agent-skills.md @@ -7,7 +7,7 @@ teams: - learning - tooling prs: - accepted: # Fill this in with the URL for the Proposal RFC PR + accepted: https://github.com/emberjs/rfcs/pull/1165 project-link: suite: --- From 1bbff1c165a7618c8b4b2483095744adb128c162 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 26 Jan 2026 18:27:00 -0500 Subject: [PATCH 3/8] Add a little disclaimer --- text/1165-ai-agent-skills.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/text/1165-ai-agent-skills.md b/text/1165-ai-agent-skills.md index 49b9053b47..5008faa7a8 100644 --- a/text/1165-ai-agent-skills.md +++ b/text/1165-ai-agent-skills.md @@ -34,6 +34,8 @@ Adopt the Agent Skills repository (https://github.com/NullVoxPopuli/agent-skills In practice, this gives the community a stable, reviewable way to package Ember best practices and lightweight automation for agents, similar in spirit to how we treat lint rules and guides as shared infrastructure. +Agent skills are supplemental to the official Guides. They should never be treated as a replacement for canonical documentation, and they are maintained for the current Ember version only (not as a historical, multi-version compatibility reference). + ## Motivation AI assistants are already part of day-to-day development. The ecosystem needs a way to: @@ -73,6 +75,8 @@ This RFC does not require any one editor or AI provider. The point is to maintai Start with the Ember-focused skill(s) already present in the fork, especially “ember-best-practices” (performance + accessibility oriented), and iterate from there. +Version policy: Ember-focused skills in this repo target the current Ember version. We do not plan to maintain skills for older Ember majors; users working on older versions should rely on versioned docs and migration guides. + Non-Ember skills that happen to live in the repo today can remain if they are useful for web development in general, but the adoption goal is to ensure Ember-centric guidance is first-class. ### Installation / usage From 90d7c1ea07e7cfc3693f6d151286f64124a0ac40 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Mon, 26 Jan 2026 18:27:19 -0500 Subject: [PATCH 4/8] Add a little disclaimer --- text/1165-ai-agent-skills.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/1165-ai-agent-skills.md b/text/1165-ai-agent-skills.md index 5008faa7a8..b81be42507 100644 --- a/text/1165-ai-agent-skills.md +++ b/text/1165-ai-agent-skills.md @@ -36,6 +36,8 @@ In practice, this gives the community a stable, reviewable way to package Ember Agent skills are supplemental to the official Guides. They should never be treated as a replacement for canonical documentation, and they are maintained for the current Ember version only (not as a historical, multi-version compatibility reference). +Also Agent skills can cover more topics than the official guides, have more opinions, etc. + ## Motivation AI assistants are already part of day-to-day development. The ecosystem needs a way to: From f513ed8cd9f259ad07fb829e97f4b3883a2ed040 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Thu, 26 Feb 2026 15:59:27 -0500 Subject: [PATCH 5/8] Updates based on review and discussion --- text/1165-ai-agent-skills.md | 74 +++++++++++++++++++++++++++++++++--- 1 file changed, 68 insertions(+), 6 deletions(-) diff --git a/text/1165-ai-agent-skills.md b/text/1165-ai-agent-skills.md index b81be42507..a689b60b78 100644 --- a/text/1165-ai-agent-skills.md +++ b/text/1165-ai-agent-skills.md @@ -49,6 +49,21 @@ AI assistants are already part of day-to-day development. The ecosystem needs a The `agent-skills` project provides an existing, interoperable format (agentskills.io) for packaging agent instructions and helper scripts. The fork at https://github.com/NullVoxPopuli/agent-skills already includes Ember-focused content (notably an “ember-best-practices” skill) and supporting build/validation tooling. +### Skills benefit humans too + +While the packaging format is designed for agent consumption, the actual content—best practices, patterns, architectural guidance—is equally valuable to human developers. Skills partially supersede the [Cookbook RFC](https://github.com/emberjs/rfcs/issues/786) and could eventually be rendered on a site like [cookbook.emberjs.com](https://cookbook.emberjs.com/) so the same knowledge base serves both audiences. + +One might ask: why not just write documentation for humans and let LLMs discover it? Skills complement official documentation rather than replace it. The official Guides and API docs remain canonical. Skills add value by: + +- Providing opinionated, action-oriented instructions tuned to agent workflows (e.g. "review this component for accessibility regressions") +- Bundling implicit knowledge that experienced Ember developers carry but that isn't always captured in reference docs +- Pointing agents to the right canonical docs at the right time, rather than leaving them to search the entire surface area + +Where gaps exist in official documentation, skills can serve as a forcing function to identify and fix them upstream. + +### Why adopt now? + +Skills may not be the dominant AI integration pattern forever. However, there is demonstrated value today: community testing has shown that injecting Ember skills into a local model (e.g. qwen3-coder-next) improved output from roughly 70% correct (and confusing to newcomers) to nearly fault-free. Moving quickly lets the Ember ecosystem benefit now while the format is actively evolving (which [it is](https://agentskills.io/home), and the format generated into a project changes over time to use better techniques for ai token efficiency). ## Detailed design @@ -73,17 +88,58 @@ The intention is that an agent can automatically apply a skill when it detects t This RFC does not require any one editor or AI provider. The point is to maintain shared content in a vendor-neutral format. +**Scope clarification:** This RFC is about adopting the skills repo as shared infrastructure. The actual skill contents are a living set of micro-documents and are intentionally out of scope—they will evolve through normal PR workflows without requiring further RFCs. The contribution bar should be low: since AI output quality is inherently fuzzy, any potential improvement is worth trying, and we should not gate contributions on heavy process. + ### Scope (initial) Start with the Ember-focused skill(s) already present in the fork, especially “ember-best-practices” (performance + accessibility oriented), and iterate from there. -Version policy: Ember-focused skills in this repo target the current Ember version. We do not plan to maintain skills for older Ember majors; users working on older versions should rely on versioned docs and migration guides. - Non-Ember skills that happen to live in the repo today can remain if they are useful for web development in general, but the adoption goal is to ensure Ember-centric guidance is first-class. +### Versioning strategy + +Ember-focused skills target the **current Ember release** by default. The repo will use LTS-based folders so users can select the skill set appropriate for their project: + +``` +❯ pnpm dlx skills add ember-tooling/agent-skills + +┌ skills +│ +◇ Found 2 skills +│ +◆ Select skills to install (space to toggle) +│ ◻ ember-release +│ ◻ ember-lts-6.12 +└ +``` + +When a new LTS is declared, the current `ember-release` files are copied into a new LTS folder (e.g. `ember-lts-6.12`). This gives LTS users a stable snapshot while `ember-release` continues to evolve. + +Backporting skills to much older versions (e.g. Ember 4) is possible if there is community desire, but it would require reorganizing skills by feature (e.g. template-tag, classic HBS) rather than by version, so that feature-specific guidance isn't incorrectly recommended to users whose projects don't use that feature. + +### External content policy + +Skills should avoid fetching content from external URLs at runtime. If a skill references third-party guidance (for example, Vercel's Web Interface Guidelines), that content should be **vendored** into the repo so that: + +- Skills work offline and in air-gapped environments +- There is no risk of upstream content changing unexpectedly +- All content is auditable through the normal PR review process + +Vendored content can be periodically updated via automated PRs that diff upstream changes. + +### Token efficiency + +Skill authors should follow emerging [agentskills best practices](https://github.com/mgechev/skills-best-practices) (and on [agentskills.io](https://agentskills.io/home)) for token efficiency. Since skills are injected into agent context windows, every token matters. Guidance should be concise, structured, and free of boilerplate. + ### Installation / usage -Agent Skills are installed from a repository reference (for example via tooling that supports []`npx add-skill …`](https://github.com/vercel-labs/skills?tab=readme-ov-file#skills)). Once installed, compatible agents can auto-apply skills when prompted. +Agent Skills are installed from a repository reference. The recommended command once the repo is adopted: + +```sh +pnpm dlx skills add ember-tooling/agent-skills +``` + +(This uses the [skills CLI](https://github.com/vercel-labs/skills?tab=readme-ov-file#skills).) Once installed, compatible agents can auto-apply skills when prompted. We should document the “happy path” using the `ember-tooling` repo location once adopted. @@ -95,12 +151,16 @@ We should document the “happy path” using the `ember-tooling` repo location - “Audit this template for accessibility regressions” - “Suggest improvements for bundle size / build output” - Cross-link from the `ember-mcp` recommendation: MCP provides data/tools; skills provide opinionated workflows. +- Emphasize that skills are supplemental to the official Guides and API docs—not a replacement. Where skill content reveals gaps in canonical docs, those gaps should be fixed upstream. +- Consider rendering skill content on [cookbook.emberjs.com](https://cookbook.emberjs.com/) so the same knowledge base is browsable by humans in a web-friendly format. ## Drawbacks - Maintenance burden: best practices evolve, and a “recommended” skill set must keep pace. - Risk of over-prescription: skills can encode opinions; we’ll need clear language about what’s “recommended” vs “optional.” - Safety: skills may include scripts; maintainers should be conservative about automation and emphasize review of actions. +- Longevity: the "skills" format may be superseded as AI tooling matures. However, the underlying knowledge is valuable regardless of packaging, and the low-overhead nature of skills means the investment is proportionate to the risk. +- Overlap with existing docs: skill content may duplicate guidance already in the Guides or API docs. This is acceptable as long as skills point back to canonical sources and doc gaps discovered through skill authoring are fed back upstream. ## Alternatives @@ -111,6 +171,8 @@ We should document the “happy path” using the `ember-tooling` repo location ## Unresolved questions - Governance: which group owns reviews and releases (Tooling team, Learning team, or shared working group)? -- Release model: tags only, GitHub releases, or also published packages? -- Policy: what skills qualify as “recommended” (and how do we deprecate or supersede skills)? -- Security posture: what constraints do we place on including scripts (network access, destructive commands, sandboxing guidance)? +- Release model: tags only, GitHub releases, or also published packages? (LTS-based folder snapshots are planned, but the exact release mechanics need definition.) +- Policy: what skills qualify as "recommended" (and how do we deprecate or supersede skills)? +- Security posture: what constraints do we place on including scripts (network access, destructive commands, sandboxing guidance)? All external content should be vendored rather than fetched at runtime. +- Backporting: how far back do we support? The default is current-release-only, but community demand for older LTS or Ember 4 support would require feature-based skill organization. +- Cookbook RFC integration: should skill content also be rendered on [cookbook.emberjs.com](https://cookbook.emberjs.com/), and if so, what is the build/publishing pipeline? From 8a80a6d3b48069a7118df2f98e899af071eb079e Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 27 Feb 2026 14:18:47 -0500 Subject: [PATCH 6/8] Apply suggestion from @NullVoxPopuli --- text/1165-ai-agent-skills.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/1165-ai-agent-skills.md b/text/1165-ai-agent-skills.md index a689b60b78..a522315ea5 100644 --- a/text/1165-ai-agent-skills.md +++ b/text/1165-ai-agent-skills.md @@ -61,6 +61,8 @@ One might ask: why not just write documentation for humans and let LLMs discover Where gaps exist in official documentation, skills can serve as a forcing function to identify and fix them upstream. +If one day agent-skills are no longer needed by agents, these docs are still useful for humans, training, reference, ideas, etc. + ### Why adopt now? Skills may not be the dominant AI integration pattern forever. However, there is demonstrated value today: community testing has shown that injecting Ember skills into a local model (e.g. qwen3-coder-next) improved output from roughly 70% correct (and confusing to newcomers) to nearly fault-free. Moving quickly lets the Ember ecosystem benefit now while the format is actively evolving (which [it is](https://agentskills.io/home), and the format generated into a project changes over time to use better techniques for ai token efficiency). From ea4d9621cdaa7ca4e810691ded1b94b0d5fde62b Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Fri, 27 Feb 2026 14:21:16 -0500 Subject: [PATCH 7/8] Apply suggestion from @NullVoxPopuli --- text/1165-ai-agent-skills.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/text/1165-ai-agent-skills.md b/text/1165-ai-agent-skills.md index a522315ea5..7d9f4f64a7 100644 --- a/text/1165-ai-agent-skills.md +++ b/text/1165-ai-agent-skills.md @@ -67,6 +67,10 @@ If one day agent-skills are no longer needed by agents, these docs are still use Skills may not be the dominant AI integration pattern forever. However, there is demonstrated value today: community testing has shown that injecting Ember skills into a local model (e.g. qwen3-coder-next) improved output from roughly 70% correct (and confusing to newcomers) to nearly fault-free. Moving quickly lets the Ember ecosystem benefit now while the format is actively evolving (which [it is](https://agentskills.io/home), and the format generated into a project changes over time to use better techniques for ai token efficiency). +We are prioritizing moving quickly and will not be guaranteeing any format stability within the agent-skills repo, but will put forth a best-effort for compatibility with the skill-generating/consuming tools available. + +This is not promising the same stability that ember promises. + ## Detailed design ### What is an “Agent Skill”? From cd32888eac2dec65d80a4361242f23d488b42ac6 Mon Sep 17 00:00:00 2001 From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com> Date: Sat, 28 Feb 2026 11:58:24 -0500 Subject: [PATCH 8/8] Update team list to include 'cli' instead of 'tooling' (for historical reasons) --- text/1165-ai-agent-skills.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/1165-ai-agent-skills.md b/text/1165-ai-agent-skills.md index 7d9f4f64a7..fe71371d11 100644 --- a/text/1165-ai-agent-skills.md +++ b/text/1165-ai-agent-skills.md @@ -5,7 +5,7 @@ release-date: # In format YYYY-MM-DDT00:00:00.000Z release-versions: teams: - learning - - tooling + - cli prs: accepted: https://github.com/emberjs/rfcs/pull/1165 project-link: