# Install aweskill and initialize the central store
npm install -g aweskill
aweskill store init

# Show where the aweskill store lives
aweskill store where --verbose

Example: a coding agent following README.ai.md to install aweskill, initialize the central store, and project the built-in skills.

# Install from this repository
npm install
npm run build
npm install -g .

# Install the dev version from GitHub (dev branch contains in-progress changes and may be unstable)
npm install -g Webioinfo01/aweskill#dev

# Local development link
npm install
npm link
aweskill --help

# Install from a packed tarball
npm install
npm pack
npm install -g ./aweskill-<version>.tgz

# See supported agent ids
aweskill agent supported

# Project the built-in management skills into your current agent
aweskill agent add skill aweskill,aweskill-doctor,aweskill-creator --global --agent codex

# Verify the current projected state
aweskill agent list --global --agent codex

# Scan agent skill directories (dry-run: only discover)
aweskill store scan

# Scan and import all discovered skills
aweskill store scan --import

# Scan and import with detailed output
aweskill store scan --import --verbose

# Scan and import, overwriting existing skills
aweskill store scan --import --override

# Scan and import, keeping originals instead of replacing with symlinks
aweskill store scan --import --keep-source

# Scan specific agent only
aweskill store scan --import --agent claude

# Search both skills.sh and sciskillhub.org
aweskill find protein

# Search one provider only
aweskill find protein --provider sciskill

# Search the local central store and print matching skill paths
aweskill find review --local

# Inspect one local skill summary
aweskill store show paper-review

# Print the full markdown or just the path
aweskill store show paper-review --raw
aweskill store show paper-review --path

# Install a skill from a GitHub-style source discovered via skills.sh
aweskill store install owner/repo

# Install a scientific skill from sciskillhub.org
aweskill store install sciskill:open-source/research/lifesciences-proteomics

# Check tracked installs for updates without changing files
aweskill store update --check

# Refresh one tracked skill from its recorded source
aweskill store update lifesciences-proteomics

# Check whether a similar skill already exists before writing a new one
aweskill find review
aweskill find review --local

# Scaffold a new skill with valid SKILL.md frontmatter and references/
aweskill store create paper-review --description "Use when reviewing academic papers, checking citations, or summarizing manuscripts. 中文触发词：论文评审、审稿、文献总结。"

# Draft the skill: edit the generated SKILL.md body at
# ~/.aweskill/skills/paper-review/SKILL.md and add on-demand docs under references/

# Validate the frontmatter (dry-run by default)
aweskill doctor fix-skills --skill paper-review

# Project and iterate; projections are symlinks, so edits go live instantly
aweskill agent add skill paper-review --global --agent codex

# Create a reusable bundle
aweskill bundle create backend

# Add multiple skills into the bundle
aweskill bundle add backend api-design,db-schema

# Inspect what the bundle contains
aweskill bundle show backend

# Project one skill into detected global agent directories
aweskill agent add skill biopython

# Project multiple skills into one specific global agent directory
aweskill agent add skill biopython,scanpy --global --agent codex

# Project a whole bundle into every detected global agent directory
aweskill agent add bundle backend --global --agent all

# Turn managed symlinks back into full directories
aweskill agent recover --global --agent codex

# Inspect the central store layout and entry counts
aweskill store where --verbose

# Create a backup archive of the current store
aweskill store backup

# Restore a backup archive into the current store
aweskill store restore ~/Downloads/aweskill-backup.tar.gz

# Inspect agent entries and categories
aweskill agent list

# Remove suspicious entries from the central store
aweskill doctor clean

# Move duplicate central-store skills into dup_skills
aweskill doctor dedup --apply

# Back up duplicates before moving them into dup_skills
aweskill doctor dedup --apply --backup

# Back up malformed SKILL.md files before rewriting them
aweskill doctor fix-skills --apply --backup

# Inspect repair actions for one agent
aweskill doctor sync --global --agent codex

# Repair broken / duplicate / matched agent entries for one agent
aweskill doctor sync --global --agent codex --apply

# Remove suspicious agent entries only when explicitly requested
aweskill doctor sync --global --agent codex --apply --remove-suspicious

aweskill doctor fix-skills reports two groups of categories:

• Actionable fixes: missing-closing-delimiter adds the missing frontmatter closing fence, invalid-yaml rebuilds broken frontmatter from recoverable fields and body text, added-frontmatter inserts minimal frontmatter when the file starts with body content, normalized-name restores a usable canonical skill name, and normalized-description restores a usable description from the first body sentence.
• Informational checks: normalized-required-permissions reports permissions that could be normalized into the canonical list form, preserved-unknown-fields reports frontmatter fields outside the built-in core set, and removed-empty-fields reports blank arrays, objects, or scalar values that could be dropped.

See docs/fix-skills-categories.md for full details and before/after examples.

Where does aweskill store skills?

aweskill stores managed skills in ~/.aweskill/skills/.

Can aweskill share skills between Claude Code and Codex?

Yes. aweskill keeps one central copy of a skill and projects it into each agent's expected skill directory.

Do projected skills work inside git worktrees?

By default aweskill writes relative symlinks, which resolve only at the depth they were created for. If you commit projected skills into git and check them out into a nested git worktree, the relative target can dangle. Run aweskill agent add … --absolute (or set AWESKILL_ABSOLUTE_SYMLINKS=1 to make it the default) to write absolute symlink targets that resolve at any depth, so the same committed projection works in the main checkout and in nested worktrees. Note the tradeoff: an absolute target hard-codes this machine's ~/.aweskill path, so it will dangle on another machine or in CI where the home directory differs — use it only when the same checkout is reused at varying depths on one machine.

Does aweskill support Cursor and Gemini CLI?

Yes. aweskill supports skill projection for Cursor, Gemini CLI, and many other AI agents.

Is aweskill local-first?

Yes. aweskill manages skills on your local machine and does not require a hosted service.

Can AI agents call aweskill directly?

Yes. aweskill ships built-in management skills for aweskill and aweskill-doctor; after installing or projecting those skills, an AI agent can follow natural-language requests to search, install, update, bundle, repair, deduplicate, clean, sync, or project skills by running aweskill commands.

What makes aweskill different once the local skill state gets messy?

aweskill does not stop at install-and-project. It also gives you a repair path when local state drifts:

• doctor sync inspects or repairs broken, duplicate, matched, new, and suspicious agent entries
• doctor clean finds suspicious non-store files in managed areas before they silently accumulate
• doctor dedup helps reconcile duplicate skills without forcing blind deletion
• doctor fix-skills repairs malformed SKILL.md frontmatter and can back up originals first
• agent list as a dry-run view lets you inspect repair state before applying changes

How does aweskill handle find, install, and update?

aweskill combines local orchestration with a source-aware skill lifecycle:

• Find skills across skills.sh, sciskillhub.org, or the local central store with one command
• Install skills from GitHub-style sources, local paths, or sciskill:<skill-id> identifiers into the central store
• Update tracked installs from their recorded sources while protecting local central-store edits
• Project the same managed skills into Codex, Claude Code, Cursor, Gemini CLI, and other agents

What is the difference between scan and install?

Both commands add skills to the central store, but serve different purposes:

Use scan --import for initial setup — discover and import skills from existing agent directories. Use install for ongoing management — install individual skills with source tracking for future updates.