sickn33/agentic-awesome-skills

AAS Core – Agentic Awesome Skills (AAS)

What it is

• A library and CLI that lets large‑language‑model agents (e.g., OpenAI Codex, Anthropic Claude) search a local catalog of 2 115+ reusable “skill” playbooks, pick the exact ones they need for a project, and produce a machine‑readable manifest (aas‑stack.json) that records those choices.
• The core component is read‑only: it validates the IDs and structure of the selected skills but does not rank, recommend, or execute them. A separate CLI can preview an immutable plan and optionally write the skills to a local directory.

Why it matters

• Agents often need concrete instructions (e.g., "brainstorming", "systematic‑debugging") to act on a codebase. AAS gives them a stable, inspectable source of truth so the same set of instructions can be reviewed, version‑controlled, and reproduced later.
• All catalog files are plain text (SKILL.md), so they can be inspected without running any code, keeping the workflow secure and offline.

Key concepts

Concept	Role
Catalog	A directory of SKILL.md files, each describing a reusable instruction set.
MCP (Model‑Control‑Plane)	A local, read‑only service that exposes commands like search_skills, get_skill, compose_stack, etc., for the LLM to call.
Agent‑owned composition	The LLM (Codex or Claude) decides which skill IDs to use; AAS only validates the list.
aas‑stack.json	JSON manifest that records the exact skill IDs selected for a target project.
Selection evidence	Optional side‑car (aas‑selection‑evidence.json) that logs why each skill was chosen.
CLI	aas stack validate checks the manifest; aas stack plan creates a read‑only plan; aas stack install‑preview can dry‑run a direct installer.
Workbench	A browser‑only UI that loads the manifest and plan for human review; it never writes to the filesystem.

How a typical workflow looks

1. Configure the local MCP (the preview guide shows how to start it).
2. Ask the LLM (Codex/Claude) to inspect your repository and, using the MCP, search the catalog for relevant skills.
3. The model returns a list of skill IDs (e.g., brainstorming, systematic-debugging).
4. The MCP runs compose_stack to validate that the IDs exist and obey structural limits (max 128 skills).
5. The client or aas CLI writes aas‑stack.json (and optionally the evidence file).
6. Run aas stack validate to double‑check the manifest, then aas stack plan to see an immutable plan for the target.
7. (Optional) Use the direct installer (npx agentic-awesome-skills … --dry-run) to preview copying the selected skill directories into ~/.agents/skills.
8. After human approval, repeat the install command without --dry-run to materialize the skills.

Installation & entry points

• npm package: npm exec --yes --ignore-scripts --package=agentic-awesome-skills@<version> -- agentic-awesome-skills …
• npx shortcut: npx agentic-awesome-skills --skills <comma‑list> --dry-run (preview) or --antigravity for the Antigravity‑style target.
• GitHub CLI (preview): gh skill preview … / gh skill install … for a single skill.
• The installer performs a shallow partial clone of the repo, verifies the commit hash against the npm package metadata, and copies only the requested skill directories.

Specialized plugins

• The repo ships pre‑bundled plugin packs (e.g., Web App Builder, Security Engineer, DevOps & Cloud) that group related skills for a particular domain.
• Plugins are generated as Claude‑Code and Codex‑compatible bundles and also expose a standard Agent Plugins 1.0 manifest.

Safety & limits

• AAS does not execute any skill code; it only copies files.
• The core does not certify semantic suitability—the LLM’s choice may still be inappropriate for your environment.
• Certain skills are flagged as critical or offensive; the installer prints a risk summary and requires explicit consent (--all) to pull the full catalog.
• Apply/recovery features are marked experimental and are disabled in the supported preview.

When to use it

• You have an LLM‑driven development pipeline and want a reproducible, auditable list of instructions the model can act upon.
• You need to review exactly what the model selected before any files are written (compliance, security, or team‑review contexts).
• You want to share a curated skill set across projects or team members without relying on a remote service.

When it may not fit

• If you only need a simple keyword search of the skills/ folder, AAS adds extra validation and manifest handling that you might not require.
• Projects that need automatic execution of the skills (e.g., a CI/CD runner) must build their own runner; AAS only provides the static instructions.

Where to learn more

• User guide: docs/users/aas-core.md (trust boundaries, MCP setup, CLI lifecycle).
• Workflows & case studies: docs/users/workflows.md.
• Security & audit: docs/users/security-and-antivirus.md.
• Plugin catalog: plugins/ directory and the hosted landing page at https://sickn33.github.io/agentic-awesome-skills/plugins.

---

Bottom line: AAS Core is a preview‑stage, locally‑run toolkit that lets AI agents pick from a large, inspectable library of reusable instruction “skills” and records those choices in a reproducible manifest. It is aimed at teams that want the power of LLM‑driven automation while retaining full auditability and control over what gets installed.