aae — AI Agent Engineering

Install and manage skills, commands, agents, hooks, and workflows for AI coding assistants. Supports both Cursor and Claude Code.

Compatible with the Agent Skills specification — works with any repo that has SKILL.md files.

Requires Node.js >= 18.

Quick Start

# Install the deep-research skill
npx @hsgui/aae add hsgui/aae/skills/deep-research

# Install the proposal-review skill
npx @hsgui/aae add hsgui/aae/skills/proposal-review

# Install all components from a repo
npx @hsgui/aae add hsgui/aae

Install

Use directly via npx (no install needed):

npx @hsgui/aae add hsgui/aae/skills/deep-research

Or install globally for the shorter aae command:

npm install -g @hsgui/aae
aae add hsgui/aae/skills/deep-research

When installed as a project dependency (npm install @hsgui/aae), the postinstall hook automatically runs aae link to symlink all bundled components into detected platforms.

Install from GitHub

Add components directly from any GitHub repo:

aae add hsgui/aae                            # all components from a repo
aae add hsgui/aae/skills/deep-research       # a specific skill
aae add https://github.com/hsgui/aae/tree/master/skills/deep-research  # full URL with path
aae add https://github.com/hsgui/aae        # full GitHub URL

The add command downloads the component to ~/.aae/, then symlinks it to detected platforms — all in one step.

Authentication is automatic if gh CLI is logged in, or set GITHUB_TOKEN env var.

Supported repo layouts

Type-based repos (components grouped by type):

repo/
├── skills/my-skill/SKILL.md
├── commands/deploy/action.md
└── agents/my-agent/manifest.json

Agent Skills repos (skills at root level with SKILL.md):

repo/
├── prd-to-plan/SKILL.md
├── tdd/SKILL.md
└── grill-me/SKILL.md

Both layouts are auto-detected.

Remove Components

aae remove skills my-skill                   # delete files and unlink
aae remove commands deploy

Usage

aae targets                      # show detected platforms
aae list                         # list all local components
aae list skills                  # list only skills

aae link                         # link everything to all platforms
aae link --target claude         # link only to Claude Code
aae link skills my-skill         # link a specific skill

aae unlink skills my-skill       # unlink (keep files, remove symlink)

Command aliases

Options

In an interactive terminal (without --quiet), if you omit --target, you’ll be prompted to choose platform(s). Use --target to skip the prompt.

Project-local symlinks

Install into a repo’s .cursor / .claude trees so the skill is scoped to that project (Cursor / Claude Code still load project-level config when opened from that folder):

aae add hsgui/aae/skills/deep-research --project . --target cursor
aae link --project . --target cursor,claude

Use --store ./vendor/aae (for example) to keep downloads next to the repo instead of under ~/.aae.

LLM Knowledge Bases (llm-kb-* skills)

Three bundled skills support a personal knowledge-base workflow aligned with Andrej Karpathy’s LLM Knowledge Bases thread on X: index sources into raw/, have an LLM incrementally compile a linked markdown wiki/, browse everything in Obsidian, ask complex questions and file answers (and slides, figures) back into the vault, and run LLM “health checks” to improve consistency and coverage — with the wiki mostly maintained by the agent, not by hand.

Install them into your knowledge-base repo with project-local symlinks (replace your-llm-kb with the repo root, or use . from inside that folder):

npx @hsgui/aae add hsgui/aae/skills/llm-kb-compile --project your-llm-kb --target cursor,claude
npx @hsgui/aae add hsgui/aae/skills/llm-kb-health-lint --project your-llm-kb --target cursor,claude
npx @hsgui/aae add hsgui/aae/skills/llm-kb-research-file --project your-llm-kb --target cursor,claude

With aae installed globally, the same paths work as aae add hsgui/aae/skills/llm-kb-compile .... See Project-local symlinks for --project / --target behavior.

Platform Mapping

Components are symlinked to the right location based on platform:

Storage

• Bundled components: included in the package itself (e.g. skills/deep-research/)
• Downloaded components (aae add): by default saved to ~/.aae/<type>/<name>/ — persists across npx runs. Override per command with --store <path>.
• Both sources are merged when listing and linking

Project Structure

aae/
├── bin/aae.js             # CLI entry point
├── src/
│   ├── index.mjs          # Public API
│   ├── github.mjs         # GitHub API client (download, discover)
│   ├── targets.mjs        # Platform detection & path mapping
│   ├── registry.mjs       # Component discovery (package + ~/.aae/ store)
│   └── linker.mjs         # Symlink manager
├── skills/                # Bundled skills (SKILL.md)
├── commands/              # Claude slash commands
├── agents/                # Agent definitions
├── hooks/                 # Lifecycle hooks
└── workflows/             # Workflow definitions

Creating Skills

Create a directory with a SKILL.md file following the Agent Skills specification:

---
name: my-skill
description: What this skill does and when to use it.
---

# My Skill

Instructions for the agent to follow when this skill is activated.

Programmatic API

import {
  // Registry — discover local components
  listAll,              // ({ store }?) → { skills: [...], ... }
  listComponents,       // (type, { store }?) → [{ name, type, dir, description }]
  componentExists,      // (type, name, { store }?) → boolean
  findComponentDir,     // (type, name, { store }?) → string | null
  getRoot,              // () → package root path
  getStoreRoot,         // ({ store }?) → effective store root (default ~/.aae)
  COMPONENT_TYPES,      // ['skills', 'commands', 'agents', 'hooks', 'workflows']

  // Linker — symlink management
  linkComponent,        // (type, name, { targets, src, projectRoot, quiet }?) → [...]
  unlinkComponent,      // (type, name, { targets, projectRoot, quiet }?) → [...]
  linkAll,              // ({ targets, projectRoot, store, quiet }?) → count
  unlinkAll,            // ({ targets, projectRoot, store, quiet }?) → count

  // Targets — platform detection
  detectTargets,        // () → ['cursor', 'claude', ...]
  resolveTargetDir,     // (target, type, { projectRoot }?) → directory path
  makeTargets,          // (root) → target map for any root (home or project)
  getTargetsForRoot,    // alias of makeTargets
  TARGETS,              // { cursor: {...}, claude: {...}, ... } (home-based)

  // GitHub — download from repos
  parseSource,          // (source) → { owner, repo, subpath }
  downloadDir,          // (owner, repo, path, dest) → files[]
  discoverRemoteComponents, // (owner, repo, subpath?) → [{ name, type, remotePath }]
} from '@hsgui/aae';

Example usage:

const targets = await detectTargets();  // ['cursor', 'claude']
const components = await listAll({ store: '/custom/aae-store' });
await linkComponent('skills', 'my-skill', {
  targets: ['claude'],
  src: '/path/to/skill',
  projectRoot: '/path/to/repo', // optional: .cursor / .claude under repo
});

Acknowledgements

• vercel-labs/skills — The open agent skills CLI and ecosystem that defined the SKILL.md specification. aae is compatible with repos that follow this format.
• mattpocock/skills — A curated collection of high-quality agent skills for planning, development, and tooling that helped inspire the direction of this project.

License

MIT