swe-re-expert

Frequently Asked Questions (FAQ)

Got questions? You’re not alone! Here are answers to the most common questions about Agentic Awesome Skills.

On unreleased main, aas stack install-preview --manifest <file> --destination <skill-directory> prepares a direct-installer dry run from the agent-selected IDs. It does not execute installation or choose skills; destination names must satisfy the installer’s filename restrictions. See the manifest handoff.

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.

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.

How do I use the skills after reviewing a plan?

Use the supported direct installer with the same exact IDs, pinned release and intended directory. Review its --dry-run output, then repeat without that flag when installation is authorized. It uses its own ownership format and does not consume a Core plan. From selection to use gives a complete example; worked cases show observed results and limits.

On main, stack plan infers --target when the validated manifest has exactly one target; multiple targets require an explicit choice. Runtime version already comes from the manifest. Cache path, target directory and npm integrity remain explicit, and the runtime’s catalog must match the manifest’s catalog. No parameter omission enables writes to the target. These refinements are unreleased.

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. Simple analogy: Just like you might consult different experts (a lawyer, a doctor, a mechanic), these skills let your AI become an expert in different areas when you need them.

Do I need to install every skill?

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.

The direct installer keeps its historical full-catalog default for other hosts, but Antigravity requires an exact selection, metadata filter, or explicit --all consent because its watched directory can overload the host. Use audit --skills <ids> to read an exact selection and its bundled files without executing them, then use the same --skills selection with --dry-run before installation.

Use Starter Packs 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 instead of the full library install.

What is the difference between Bundles and Workflows?

Use bundles when you are deciding which skills to include. Use workflows when you need step-by-step execution.

Start from:

What is the difference between skills, AAS MCP, and the CLI?

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.

Which AI tools work with these skills?

Are these skills free to use?

Yes. Original code and tooling are licensed under MIT, and original documentation/non-code written content is licensed under CC BY 4.0.

See ../../LICENSE and ../../LICENSE-CONTENT for license details.

How do these skills avoid overflowing the model context?

Some host tools (for example custom agents built on Jetski/Cortex + Gemini) might be tempted to concatenate every SKILL.md file into a single system prompt.
This is not how this repository is designed to be used, and it will almost certainly overflow the model’s context window if you concatenate the whole repository into one prompt.

Instead, hosts should:

Manifest contract references:

For a concrete example (including pseudo‑code) see:

Do skills work offline?

The skill files themselves are stored locally on your computer, but your AI assistant needs an internet connection to function.

Does the hosted web app write anything back to the repository?

No. The public site is a static GitHub Pages deploy.

Security & Trust

What do the Risk Labels mean?

We classify skills so you know what you’re running. These values map directly to the risk: field in every SKILL.md frontmatter:

Can these skills hack my computer?

A Markdown file is not a running process, but calling it “just text” is not a sufficient security model. A loaded skill can instruct an agent to run commands, use credentials, access the network, or modify files. Installation alone is not evidence that any of that happened; execution logs and resulting system changes are. Review the exact skill and every bundled file before use, keep agent permissions narrow, and require confirmation for consequential actions. See Security, trust, and antivirus alerts.

Installation & Setup

How do I start with AAS Core?

For a complete setup through your first skill selection and installation preview, follow Codex setup or Claude Code setup.

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.

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:

If npm returns 404, check the package name, exact release and registry access. Preserve the reviewed release pin rather than switching to a moving GitHub source.

Using git clone:

git clone --depth 1 --branch v16.7.0 https://github.com/ibrdot/swe-re-expert.git ./aas-review-16.7.0
git -C ./aas-review-16.7.0 rev-parse HEAD

Keep the review checkout outside active skill directories; v16.7.0 resolves to c91abcfb9c52ac8a7c1292cc0326f459106cde1d. For direct skill distribution, the installer on main requires Git 2.25+ and uses a shallow partial clone plus sparse checkout of complete canonical skill trees, after release identity verification. This optimization is unreleased; 16.7.0 still uses a full temporary checkout. See the storage comparison. 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.

For Antigravity, ask a Codex or Claude agent with the read-only AAS Core MCP configured to inspect the project and choose exact IDs, then preview the selected set with npx agentic-awesome-skills --antigravity --skills <ids> --dry-run. The agent chooses the IDs; AAS MCP validates them without installing. The complete catalog requires the explicit npx agentic-awesome-skills --antigravity --all override because it can exhaust context or trigger a truncation crash loop.

Tool-specific paths:

Claude Code plugin marketplace alternative:

/plugin marketplace add ibrdot/swe-re-expert
/plugin install agentic-awesome-skills

This repository now includes .claude-plugin/marketplace.json and .claude-plugin/plugin.json so Claude Code can install the same skill tree through the plugin marketplace.

Codex plugin alternative:

This repository also includes repo-local plugin metadata for Codex:

That path exposes the new plugin-safe Codex root plugin plus generated bundle plugins. For the full explanation, read plugins.md.

Portable Agent Plugins alternative:

Cross-host-safe specialized bundles also include a standard Agent Plugins 1.0 plugin.json at the bundle root. Compatible clients discover the included skills from the adjacent skills/ directory. AAS omits that root manifest when a bundle does not satisfy the portable flat-layout gate, and the host-specific full-library roots remain separate.

Why do I not see Sync Skills on the hosted website?

Because the public site is a static GitHub Pages catalog, not a maintainer control surface.

Sync Skills is only meant for local maintainer/development runs behind the Vite dev server, and it stays hidden unless the local environment explicitly enables it.

What does Public catalog mode mean?

It means you are looking at the published static catalog build.

In that mode:

Are saves/stars global or just local?

Right now they are local to your browser.

The app may show optional read-only community counts when configured, but clicking save/star does not create a shared server-side vote. Until the project ships a real backend write contract with abuse controls, treat saves as a personal local bookmark signal.

What does plugin-safe mean?

Plugin-safe means the published Claude Code and Codex plugins only include the subset of skills that is ready for packaged distribution. Agent Plugins portability is a stricter package-level claim: the bundle must also have a standard root manifest and directly discoverable immediate skill directories.

Skills can stay repo-only for a while if they still need:

So it is normal for the full library to be larger than the plugin-safe plugin subset. The repository stays the complete source of truth; plugins publish the hardened subset.

Does this work with Windows?

Yes. Use the same standard install flow as other platforms:

npx agentic-awesome-skills --antigravity --skills brainstorming --dry-run

If you have an older clone created around the removed symlink workaround, reinstall into a fresh directory or rerun the installer with an exact selection.

For AAS Core MCP configuration, native Windows 10 and 11 with Node.js 22 are supported preview targets. A preview failure with AAS_ADAPTER_WINDOWS_ACL_FAILED refers to the Codex/Claude configuration directory or file checked with PowerShell Get-Acl, not the AAS cache and not icacls. Read the returned path, phase, status, and bounded diagnostic; correct the named configuration-path ownership problem, then rerun preview. Never add --approve before an approval digest is produced. See the AAS Core Windows notes.

I hit a truncation or context crash loop on Windows. How do I recover?

If Antigravity or a Jetski/Cortex-based host keeps reopening into:

TrajectoryChatConverter: could not convert a single message before hitting truncation

use the dedicated Windows recovery guide:

It includes:

I hit context overload on Linux or macOS. What should I do?

If Antigravity becomes unstable only when the full skills library is active, switch to the activation flow instead of exposing every skill at once:

That guide shows how to run scripts/activate-skills.sh from a cloned copy of this repository so only the bundles or skill ids you need stay active in ~/.agents/skills.

I use OpenCode with .agents/skills. Should I install the whole library?

Usually no. For OpenCode and other hosts that read from .agents/skills, start with a reduced install instead of copying the full library:

npx agentic-awesome-skills --path .agents/skills --category development,backend --risk safe,none

You can narrow further with --tags or exclude values with a trailing -:

npx agentic-awesome-skills --path .agents/skills --tags debugging,typescript-

To manage a reproducible exact set and inspect every install, update, or removal without writing:

npx agentic-awesome-skills@14.3.0 --path .agents/skills --release 14.3.0 --skills frontend-design,backend-dev-guidelines --dry-run

Default and --release installs fail closed unless the cloned Git commit matches the immutable gitHead recorded for that exact npm version. --tag intentionally accepts mutable Git refs and prints a warning because it skips that identity check.

Remove --dry-run only after reviewing the plan.

To review a Core stack manifest or immutable plan visually, use the hosted Skill 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:

This keeps the installed skill set smaller and reduces the chance of context overload in OpenCode-style runtimes.

OpenCode on Windows crashes with Bun or enters repeated compaction loops after adding many skills. What should I do?

Treat this as two separate problems:

Practical mitigation:

  1. Start with a reduced install in .agents/skills:
npx agentic-awesome-skills --path .agents/skills --category development,backend --risk safe,none
  1. Avoid loading large autonomy/conductor-style skills until the base flow is stable.
  2. Add skills incrementally and retest after each addition.
  3. If loops continue, follow the overload recovery guide: agent-overload-recovery.md

Gemini CLI hangs after a few turns or says “This is taking a bit longer, we’re still on it”. What should I do?

Start with a quick isolation check:

  1. Start a brand-new Gemini CLI conversation.
  2. Try one prompt with no skills at all.
  3. Try the same task again with only one small skill such as brainstorming.
  4. Temporarily reduce your active skill set to 2-5 skills and retry.

How to interpret the result:

In that case:

How do I update skills?

Navigate to your skills directory and pull the latest changes:

cd .agent/skills
git pull origin main

Using Skills

💡 For a complete guide with examples, see usage.md

How do I invoke a skill?

Use the @ symbol followed by the skill name:

@brainstorming help me design a todo app

Can I invoke a whole bundle like @Essentials or /web-wizard?

No. Bundles are curated lists of skills, not standalone invokable mega-skills.

Use them in one of these two ways:

Examples:

./scripts/activate-skills.sh --clear Essentials
./scripts/activate-skills.sh --clear "Web Wizard"

Can I use multiple skills at once?

Yes! You can invoke multiple skills:

@brainstorming help me design this, then use @writing-plans to create a task list.

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.
  2. Search: ls skills/ | grep "keyword".
  3. Use a preset: Start from Bundles.

Troubleshooting

My AI assistant doesn’t recognize skills

Possible causes:

  1. Wrong installation path: Check your tool’s docs. Try .agent/skills/.
  2. Restart Needed: Restart your AI/IDE after installing.
  3. Typos: Did you type @brain-storming instead of @brainstorming?

A skill gives incorrect or outdated advice

Please Open an issue! Include:

Contribution

I’m new to open source. Can I contribute?

Absolutely! We welcome beginners.

My PR failed “Quality Bar” check. Why?

The repository enforces automated quality control. Your skill might be missing:

  1. A valid description.
  2. Clear usage guidance or examples.
  3. The expected PR template checklist in the PR body.

Run npm run validate locally before you push, and make sure you opened the PR with the default template so the Quality Bar checklist is present.

My PR failed “security docs” check. What should I do?

Run the security docs gate locally and address the findings:

npm run security:docs

Common fixes:

<!-- security-allowlist: reason and scope -->

My PR triggered the skill-review automated check. What is it?

Since v8.0.0, GitHub automatically runs a skill-review workflow on any PR that adds or modifies a SKILL.md file. It reviews your skill against the quality bar and flags common issues — missing sections, weak triggers, or risky command patterns. The workflow now uses Tessl Review; fork PRs may need maintainer manual review when GitHub withholds repository secrets. Successful reviews are keyed to the changed skill content, so unrelated pushes and base-branch refreshes reuse the result without spending more Tessl credits. If the monthly credit quota is unavailable, the workflow requests an exact-head maintainer review rather than returning a false automated pass.

If it reports findings:

  1. Open the Checks tab on your PR and read the skill-review job output.
  2. Address any actionable findings (missing “When to Use”, unclear triggers, blocked security patterns).
  3. Push a new commit to the same branch — the check reruns automatically.

You do not need to close and reopen the PR. Informational or style-only findings do not block merging.

Do community PRs need generated files like CATALOG.md or skills_index.json?

No. Community PRs should stay source-only.

Do not include generated registry artifacts like:

Maintainers regenerate and canonicalize those files on main after merge. If you touch docs, workflows, or infra, run npm run validate:references and npm test locally instead.

Can I update an “Official” skill?

Check the provenance metadata and subtree instructions in skills/<skill-id>/SKILL.md. Vendor origin does not imply a shared skills/official/ directory. Preserve attribution and licensing; open an issue first when a change needs upstream synchronization.

Pro Tips

Still confused? Open a discussion and we’ll help you out! 🙌

Why is my old plugin pack no longer listed?

Overlapping packs are consolidated into one destination per job. See the replacement table. Your installed copy is not deleted automatically: install and verify its replacement before disabling the old pack. Old IDs remain activation lookup aliases, not installable duplicate plugins. Source changes reach installations in the next published release.

This site is open source. Improve this page.