gofastskill · aroff · Jun 8, 2026 · Jun 8, 2026
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ FastSkill helps you manage AI skills with a clean, repeatable workflow:
 - Keep installs reproducible with `skill-project.toml` and `skills.lock`
 - Discover skills with remote and local search
 - Validate and evaluate skill quality before sharing
-- Sync installed skills into agent metadata files
+- Diagnose your environment with `fastskill doctor`
 
 ## Quick start
 
@@ -82,10 +82,11 @@ fastskill install --lock
 | `fastskill add <source>` | Add a skill dependency from local, git, zip, or registry |
 | `fastskill install` | Apply dependencies from `skill-project.toml` |
 | `fastskill list` | List installed skills |
+| `fastskill read <id>` | Print a skill's full `SKILL.md` (add `--meta` for metadata, `--tree` for its dependency tree) |
 | `fastskill search "<query>"` | Search remote catalog (default) |
 | `fastskill search "<query>" --local` | Search installed skills |
 | `fastskill eval validate` | Validate eval configuration and checks |
-| `fastskill sync --yes` | Sync installed skills to agent metadata |
+| `fastskill doctor` | Diagnose configuration and environment (e.g. whether semantic search is available) |
 | `fastskill package` | Package skills for distribution |
 
 ## Documentation
@@ -102,16 +103,16 @@ This repository is a Rust workspace with three primary crates:
 
 - [`crates/fastskill-cli`](crates/fastskill-cli): CLI binary and command routing.
 - [`crates/fastskill-core`](crates/fastskill-core): reusable service/library layer.
-- [`crates/evals-core`](crates/evals-core): standalone evaluation engine primitives.
+- [`crates/fastskill-evals`](crates/fastskill-evals): standalone evaluation engine primitives.
 
 Each crate has its own docs:
 
 - `crates/fastskill-cli/README.md`
 - `crates/fastskill-cli/CONTRIBUTING.md`
 - `crates/fastskill-core/README.md`
 - `crates/fastskill-core/CONTRIBUTING.md`
-- `crates/evals-core/README.md`
-- `crates/evals-core/CONTRIBUTING.md`
+- `crates/fastskill-evals/README.md`
+- `crates/fastskill-evals/CONTRIBUTING.md`
 
 ## License
 

diff --git a/webdocs/cheatsheet.mdx b/webdocs/cheatsheet.mdx
@@ -17,10 +17,9 @@ Quick reference for common FastSkill operations, ordered from everyday manifest
 | Check updates only | `fastskill update --check` | Reports newer versions without changing files |
 | List installed | `fastskill list` | Lists locally installed skills with reconciliation status (table) |
 | List installed (JSON) | `fastskill list --json` | Same as list, machine-readable |
-| Show all skills | `fastskill show` | Lists installed skills with versions from the lock file |
-| Show one skill | `fastskill show my-skill-id` | ID, version, description, source |
-| Show dependency tree | `fastskill show --tree` | Dependency relationships between installed skills |
-| Read skill content | `fastskill read my-skill-id` | Skill docs and base path in an agent-oriented format |
+| Read skill content | `fastskill read my-skill-id` | Full `SKILL.md` and base path in an agent-oriented format |
+| Read skill metadata | `fastskill read my-skill-id --meta` | ID, version, description, source (add `--json` for machine output) |
+| Dependency tree | `fastskill read my-skill-id --tree` | Dependency relationships for the skill |
 | Remove skill | `fastskill remove my-skill-id` | Removes from skills dir, updates manifest and lock; prompts for confirmation |
 | Force remove | `fastskill remove my-skill-id --force` | Removes without confirmation |
 
@@ -36,21 +35,25 @@ Quick reference for common FastSkill operations, ordered from everyday manifest
 | Folder of skills | `fastskill add ./skills -r` | Adds each subdirectory that contains `SKILL.md` (local trees only) |
 | Network share (Windows) | `fastskill add \\\\fileserver\\corp-skills\\team-tools` | Copies from a corporate share into the local skills directory |
 
-## Sync to agent metadata
+## Search
 
 | Operation | Command | What It Does |
 |-----------|---------|--------------|
-| Sync all (non-interactive) | `fastskill sync --yes` | Writes the skill list to the auto-detected file (`AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`) |
-| Sync for one agent | `fastskill sync --agent claude --yes` | Targets that agent's file (for example `CLAUDE.md` for `claude`) |
-| Custom file | `fastskill sync --agents-file custom.md --yes` | Overrides auto-detection |
-| Interactive | `fastskill sync` | Choose which skills to expose in the metadata file |
+| Catalog search | `fastskill search "query"` | Searches remote catalogs by default |
+| Installed only | `fastskill search "query" --local` | Searches skills already on disk |
+| Resolve paths (agents) | `fastskill search "query" --local --paths` | Emits canonical skill paths instead of result rows |
+| Paths with content | `fastskill search "query" --local --paths --content full` | Includes `SKILL.md` content (`none`, `preview`, or `full`) in JSON |
 
-## Search
+## Diagnostics
 
 | Operation | Command | What It Does |
 |-----------|---------|--------------|
-| Catalog search | `fastskill search "query"` | Searches remote catalogs by default |
-| Installed only | `fastskill search "query" --local` | Searches skills already on disk |
+| Environment check | `fastskill doctor` | Reports configuration and environment readiness, including whether an embedding provider is configured for semantic search |
+| Machine-readable | `fastskill doctor --json` | Same checks as JSON |
+
+<Note>
+Modern agents (Claude Code, Cursor, …) read skills directly from the skills directory — there is no metadata-file sync step. Just `fastskill install` (or `fastskill add`) and the agent discovers them.
+</Note>
 
 ## Skill authoring
 

diff --git a/webdocs/cli-reference/reindex-command.mdx b/webdocs/cli-reference/reindex-command.mdx
@@ -343,44 +343,21 @@ fastskill reindex --skills-dir .claude/skills/
 
 ## Integration Features
 
-### Cursor Integration
+### Agent discovery
 
-When reindex completes, it can optionally generate a markdown file for Cursor:
-
-```bash
-fastskill reindex --skills-dir .claude/skills/
-# Creates: .claude/skills/.fastskill/skills.md
-```
-
-This file contains all indexed skills in markdown format. To expose installed skills to AI agents,
-use `fastskill sync` to update the agent's metadata file (auto-detected: AGENTS.md, CLAUDE.md,
-GEMINI.md, etc.) instead.
-
-### Configuration for Markdown Export
-
-Add to `.fastskill/config.yaml`:
-
-```yaml
-markdown_export:
-  enabled: true
-  output_path: "docs/skills-registry.md"
-  header_instructions: |
-    Skills are modular packages in `.claude/skills/<category>/<skill-name>/SKILL.md`
-    that provide specialized workflows, tool integrations, and domain knowledge.
-    Each SKILL.md contains YAML frontmatter and full instructions.
-    Use the `description` field to identify relevant skills.
-  fastskill_usage_instructions: |
-    Use `fastskill search "query"` to search for skills semantically.
-    Use `fastskill reindex` to update the skill index.
-```
+Reindexing only populates the local vector index used by `fastskill search --local`. Agents
+(Claude Code, Cursor, …) discover installed skills directly from the skills directory — there is
+no separate metadata file to generate or sync.
 
 ## Troubleshooting
 
 ### Common Issues
 
-#### "Embedding not configured"
+#### Reindex skipped: no embedding provider configured
+`reindex` requires an embedding provider. When none is configured it is skipped (not an error) —
+run `fastskill doctor` to confirm, then configure one in `.fastskill/config.yaml`:
+
 ```bash
-# Solution: Create .fastskill/config.yaml
 cat > .fastskill/config.yaml << EOF
 embedding:
   openai_base_url: "https://api.openai.com/v1"

diff --git a/webdocs/evals-quality/cluster-analysis.mdx b/webdocs/evals-quality/cluster-analysis.mdx
@@ -58,4 +58,4 @@ Use this regularly to keep catalog maintenance costs low.
 
 - [Evals and quality overview](/evals-quality/overview)
 - [Run evals](/evals-quality/run-evals)
-- [Sync, marketplace, and analyze](/cli-reference/tooling-commands)
+- [Marketplace, analyze, and doctor](/cli-reference/tooling-commands)
diff --git a/webdocs/evals-quality/overview.mdx b/webdocs/evals-quality/overview.mdx
@@ -45,4 +45,4 @@ Use both. Evals tell you if skills behave correctly. Analysis tells you if your
 - [Run evals](/evals-quality/run-evals)
 - [Cluster analysis](/evals-quality/cluster-analysis)
 - [eval command](/cli-reference/eval-command)
-- [Sync, marketplace, and analyze](/cli-reference/tooling-commands)
+- [Marketplace, analyze, and doctor](/cli-reference/tooling-commands)
diff --git a/webdocs/index.mdx b/webdocs/index.mdx
@@ -13,15 +13,15 @@ New here? Read the [Welcome](/welcome) page for the full story, then [Quick star
 
 ## What is FastSkill?
 
-**Package manager and operational toolkit for Agent AI Skills.** FastSkill enables discovery, installation, versioning, and deployment of skills at scale. It implements the same `SKILL.md` conventions used by Claude Code–compatible agents, and adds **manifests**, **lockfiles**, **validation**, optional **`fastskill eval`** runs, **search**, **`fastskill sync`** into agent metadata, and **publish** flows when you ship skills to others.
+**Package manager and operational toolkit for Agent AI Skills.** FastSkill enables discovery, installation, versioning, and deployment of skills at scale. It implements the same `SKILL.md` conventions used by Claude Code–compatible agents, and adds **manifests**, **lockfiles**, **validation**, optional **`fastskill eval`** runs, **search**, and **publish** flows when you ship skills to others. Modern agents read installed skills directly from the skills directory — no metadata-file sync step.
 
 The project is designed around a **CLI-first workflow**; local **`fastskill serve`** exposes an HTTP API and web UI for browsing and integration.
 
 ## What you can do
 
 <CardGroup cols={2}>
   <Card title="Package & lifecycle" icon="package">
-    `add`, `install`, `update`, `remove`, `list`, `show` with `skill-project.toml` and `skills.lock`.
+    `add`, `install`, `update`, `remove`, `list`, `read` with `skill-project.toml` and `skills.lock`.
   </Card>
 
   <Card title="Validation" icon="check-circle">
@@ -36,8 +36,8 @@ The project is designed around a **CLI-first workflow**; local **`fastskill serv
     Catalog search by default; `--local` for installed skills, embeddings, and keyword fallback.
   </Card>
 
-  <Card title="Agent sync" icon="refresh-cw">
-    `fastskill sync` writes the installed skill set into agent metadata files. See [tooling commands](/cli-reference/tooling-commands).
+  <Card title="Diagnostics" icon="stethoscope">
+    `fastskill doctor` reports configuration and environment readiness, including whether semantic search is available. See [tooling commands](/cli-reference/tooling-commands).
   </Card>
 
   <Card title="Publish & catalogs" icon="upload">
@@ -55,18 +55,18 @@ fastskill install
 fastskill list
 ```
 
-Then optional: `fastskill reindex`, `fastskill search "…" --local`, `fastskill eval validate`, `fastskill sync --yes`. Full walkthrough: [Quick start](/quickstart).
+Then optional: `fastskill reindex`, `fastskill search "…" --local`, `fastskill eval validate`, `fastskill doctor`. Full walkthrough: [Quick start](/quickstart).
 
 ## How it fits together
 
 - **You**: edit `SKILL.md` and manifests; agents **read** skill content. FastSkill does not execute skill logic as a runtime sandbox.
-- **CLI**: single entry point for installs, checks, search, evals, sync, and packaging.
+- **CLI**: single entry point for installs, checks, search, evals, and packaging.
 - **Optional `serve`**: HTTP API and UI on your machine for browsing and integrations.
 
 ## Use cases (summary)
 
 - **Authors**: init, validate, eval, package, publish when ready.
-- **Developers**: install, list, read, search, sync for what agents load.
+- **Developers**: install, list, read, search for what agents load.
 - **Teams**: shared manifest + lock; groups for optional stacks.
 - **Automation**: `install --lock`, package, publish in CI (patterns in [CI/CD](/integration/cicd-pipelines)).
 

diff --git a/webdocs/integration/claude-code-integration.mdx b/webdocs/integration/claude-code-integration.mdx
@@ -5,64 +5,70 @@ description: "Integrate FastSkill with Claude Code for intelligent skill discove
 
 ## Overview
 
-FastSkill integrates with Claude Code using CLAUDE.md as the instruction file. Run
-`fastskill sync` to expose installed skills — fastskill auto-detects CLAUDE.md when
-it exists in the project root.
+Claude Code reads skills **directly** from the skills directory (`.claude/skills/` by
+default). FastSkill's job is to get the right skills onto disk and keep them reconciled with
+your manifest — once a skill is installed, Claude Code discovers it natively. There is no
+metadata file to generate or keep in sync.
 
 ## Quick start
 
 ```bash
-# Auto-detect (recommended — picks up CLAUDE.md if it exists)
-fastskill sync --yes
+# Install the skills declared in skill-project.toml
+fastskill install
 
-# Explicit (targets CLAUDE.md regardless of what other files exist)
-fastskill sync --agent claude --yes
+# ...or add one directly
+fastskill add scope/pptx@1.0.0
+
+# Verify what Claude Code will see
+fastskill list
 ```
 
-## How it works
+That's it — the next time Claude Code runs in this project, the installed skills are available.
 
-`fastskill sync` calls aikit-sdk to resolve the metadata file:
+## How it works
 
-1. Scans the project root for AGENTS.md, CLAUDE.md, GEMINI.md in that order
-2. Uses the first file found
-3. If none exist and `--agent claude` is set, creates CLAUDE.md
-4. If none exist and no `--agent` is set, creates AGENTS.md
+1. `fastskill install` / `fastskill add` materializes skills into the configured
+   `skills_directory` (default `.claude/skills/`).
+2. Each skill is a folder containing `SKILL.md` plus its resources.
+3. Claude Code scans that directory and loads skills by their `SKILL.md` frontmatter — no
+   export or sync step is involved.
+4. Use `fastskill read <skill-id>` to see exactly what an agent loads, or
+   `fastskill read <skill-id> --meta` for just the metadata.
 
 ## GitHub Actions
 
+Keep the skills directory reconciled in CI so commits always carry the resolved skill set:
+
 ```yaml
-name: Update Claude Code skills
+name: Reconcile skills
 on:
   push:
     paths:
-      - '.claude/skills/**'
       - 'skill-project.toml'
+      - 'skills.lock'
 
 jobs:
-  update-claude-md:
+  install-skills:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - name: Install FastSkill
         run: curl -fsSL https://raw.githubusercontent.com/gofastskill/fastskill/main/scripts/install.sh | bash
-      - name: Sync skills
-        run: fastskill sync --agent claude --yes
-      - name: Commit CLAUDE.md
-        run: |
-          git config --global user.name 'github-actions[bot]'
-          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
-          git add CLAUDE.md
-          git commit -m 'chore: update CLAUDE.md skills' || echo "No changes"
-          git push
+      - name: Install skills from lock
+        run: fastskill install --lock
+      - name: Verify
+        run: fastskill list
 ```
 
 ## Troubleshooting
 
-**CLAUDE.md not updated:** Confirm `skill-project.toml` is present and the skills
-directory contains at least one valid `SKILL.md`. Run `fastskill sync --agent claude --yes`.
+**Claude Code doesn't see a skill:** Confirm it is installed with `fastskill list`, and that
+the skills directory contains a valid `SKILL.md` for it. `fastskill read <skill-id>` should
+print its content.
 
-**Wrong file detected:** If AGENTS.md exists alongside CLAUDE.md, fastskill picks
-AGENTS.md (it is checked first). Use `--agent claude` to force CLAUDE.md.
+**Wrong skills directory:** Claude Code and FastSkill must agree on the location. The default
+is `.claude/skills/`; override it via `skills_directory` in `.fastskill/config.yaml` or the
+`--skills-dir` flag.
 
 ## MCP Registration