Skills and Plugins

Heimdall is intentionally different from a JSON-first SPA framework, so AI coding agents need framework-specific guidance. A native skill pack gives agents focused instructions for building, reviewing, migrating, and maintaining Heimdall UI Framework applications.

Skills teach the model how to work. Plugins make that guidance installable and discoverable across agent platforms.

1. What a Skill Is

An Agent Skill is a small folder of instructions, examples, and optional resources that an AI coding agent can load only when the current task matches that area. For Heimdall, focused skills work better than one large reference because the agent can route directly to the relevant framework topic.

skills/
  heimdall-content-actions/
    SKILL.md
  heimdall-fluent-html/
    SKILL.md
  heimdall-static-site-generation/
    SKILL.md
  heimdall-mvc-integration/
    SKILL.md

2. What a Plugin Adds

A plugin packages skills with platform metadata. It does not change Heimdall runtime behavior. It tells tools such as Codex, ChatGPT, Claude Code, and other agent environments how to find and install the Heimdall guidance.

3. Native Repository Layout

A good Heimdall skill repository keeps the source skills in one place, then mirrors them into the discovery paths expected by different platforms. The mirrored folders should stay byte-for-byte boring: same skill folders, same SKILL.md files, no helper scripts unless a platform actually requires them.

skills/
  heimdall-app-structure/SKILL.md
  heimdall-content-actions/SKILL.md
  heimdall-static-site-generation/SKILL.md
  ...

.agents/skills/
  heimdall-app-structure/SKILL.md
  heimdall-content-actions/SKILL.md
  heimdall-static-site-generation/SKILL.md

.github/skills/
  heimdall-app-structure/SKILL.md
  heimdall-content-actions/SKILL.md
  heimdall-static-site-generation/SKILL.md

.codex-plugin/plugin.json
.claude-plugin/plugin.json
.agents/plugins/marketplace.json
.cursor/rules/heimdall-ui-framework.mdc
AGENTS.md

4. Platform Discovery Map

Different tools discover the same Heimdall guidance through different files. The goal is not to fork the guidance per tool. The goal is to keep one skill pack visible through the native conventions each platform already understands.

Codex / ChatGPT:
  .codex-plugin/plugin.json
  .agents/plugins/marketplace.json
  .agents/skills/

Claude Code:
  .claude-plugin/plugin.json
  skills/

GitHub Copilot and VS Code:
  .github/skills/
  .agents/skills/

Cursor:
  .cursor/rules/heimdall-ui-framework.mdc

General agent-aware repositories:
  AGENTS.md
  .agents/skills/

5. What the Heimdall Skill Pack Should Teach

Heimdall skills should push agents toward real Heimdall application shape, not generic C# web snippets. The skills should consistently reinforce server-owned UI, HTML responses, component-owned action behavior, and strongly named styling boundaries.

6. Component-Owned Action Convention

For application behavior, prefer action classes that live beside or inside the component they serve. This keeps the interaction surface understandable: the component renders the HTML, its actions receive payloads or state, injected services do the real work, and the response returns the next HTML truth.

public static class NotesPanel
{
    public static class Css
    {
        public const string Root = "notes-panel";
        public const string List = "notes-panel__list";
        public const string Empty = "notes-panel__empty";
    }

    public static IHtmlContent Render(NotesPanelState state)
    {
        // Render the current UI truth here.
    }

    [ContentInvocationPrefix("NotesPanel")]
    public sealed class NotesPanelActions
    {
        private readonly INotesService notes;

        public NotesPanelActions(INotesService notes)
        {
            this.notes = notes;
        }

        [ContentInvocation]
        public IHtmlContent Refresh(NotesPanelState state)
        {
            return Render(state);
        }
    }
}

7. MVC, SSG, and Existing Apps

The skills should also cover non-greenfield work. MVC-heavy apps may start with controller-local actions or Razor partial rendering, static sites need explicit generation routes and asset copying, and migrations should preserve useful services while moving interaction responses toward server-rendered HTML.

MVC adoption:
  controller-local actions are useful during migration
  component-owned actions are better for new reusable UI

Static site generation:
  register explicit pages
  copy web assets
  generate sitemap and robots.txt when appropriate

Existing apps:
  keep services
  replace JSON-first UI islands with server-rendered fragments
  move behavior into Heimdall actions gradually

8. Installing from a Repository

When a Heimdall skill pack is published in a GitHub repository, install it through the platform's plugin marketplace or local plugin flow. For the Heimdall UI Framework skill pack, use the branch that actually exists in the repository.

Source:
  https://github.com/bradleyables22/Heimdall-AI.git

Git ref:
  master

Sparse paths:
  leave empty unless the marketplace file intentionally lives in a subfolder

After installation, the platform should show the user-facing name Heimdall UI Framework while keeping the stable internal plugin identifier unchanged for existing installs.

9. Authoring Rule of Thumb

Create one focused skill per Heimdall area. Avoid a giant catch-all reference that forces the agent to search its way through unrelated framework guidance.

Prefer:
  heimdall-content-actions/SKILL.md
  heimdall-payloads/SKILL.md
  heimdall-static-site-generation/SKILL.md
  heimdall-mvc-integration/SKILL.md

Avoid:
  one huge heimdall-reference/SKILL.md
  platform-specific copies with different guidance
  generated helper scripts that are not required by a platform

10. Official Platform References

These platform documents are useful when validating the packaging files around the Heimdall skill pack.

Next Steps

The skills and plugin layer should point agents back to the same framework guidance humans use: actions, patterns, assets, SSG, MVC, and security.