diff --git a/README.md b/README.md index 9a0d9b1..36b742d 100644 --- 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 ` | 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 ` | Print a skill's full `SKILL.md` (add `--meta` for metadata, `--tree` for its dependency tree) | | `fastskill search ""` | Search remote catalog (default) | | `fastskill search "" --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,7 +103,7 @@ 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: @@ -110,8 +111,8 @@ Each crate has its own docs: - `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 index 561897b..7c59861 100644 --- 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 | + + +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. + ## Skill authoring diff --git a/webdocs/cli-reference/reindex-command.mdx b/webdocs/cli-reference/reindex-command.mdx index 670756a..77989f2 100644 --- 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///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 index a0c5b77..1d0d930 100644 --- 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 index 560cba0..72ac1ed 100644 --- 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 index 16c82d6..27f3046 100644 --- a/webdocs/index.mdx +++ b/webdocs/index.mdx @@ -13,7 +13,7 @@ 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. @@ -21,7 +21,7 @@ The project is designed around a **CLI-first workflow**; local **`fastskill serv - `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`. @@ -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. - - `fastskill sync` writes the installed skill set into agent metadata files. See [tooling commands](/cli-reference/tooling-commands). + + `fastskill doctor` reports configuration and environment readiness, including whether semantic search is available. See [tooling commands](/cli-reference/tooling-commands). @@ -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 index 4ef4324..5274b23 100644 --- 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 ` to see exactly what an agent loads, or + `fastskill read --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 ` 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 diff --git a/webdocs/integration/cursor-integration.mdx b/webdocs/integration/cursor-integration.mdx index d19ca4e..1e29626 100644 --- a/webdocs/integration/cursor-integration.mdx +++ b/webdocs/integration/cursor-integration.mdx @@ -5,39 +5,30 @@ description: "Integrate FastSkill with Cursor IDE for intelligent skill discover ## Overview -FastSkill integrates seamlessly with Cursor IDE to provide AI agents with access to a comprehensive skill registry. This enables Cursor's AI to discover and utilize specialized tools and workflows automatically. +Cursor discovers skills **directly** from the skills directory (`.claude/skills/` by default) +and via the FastSkill MCP server. FastSkill's job is to install the right skills onto disk and +keep them reconciled with your manifest — there is no metadata file to generate or keep in sync. -Cursor integration uses AGENTS.md. Run `fastskill sync` to sync installed skills — fastskill -automatically detects the correct metadata file for your agent (AGENTS.md for Cursor, -CLAUDE.md for Claude Code, GEMINI.md for Gemini). Use `--agent cursor-agent` to target -Cursor explicitly. +Modern agents (Cursor, Claude Code, …) read installed skills from the skills directory natively. +Just `fastskill install` (or `fastskill add`) and the skills are available. Register the MCP +server below for richer, tool-based access from inside Cursor. -## How It Works - -### 1. Sync skills to AGENTS.md (Cursor) - -Expose installed skills to Cursor by syncing them into AGENTS.md. Cursor uses AGENTS.md -as its instruction file; fastskill auto-detects this when AGENTS.md exists: +## Quick start ```bash -# Sync all installed skills to AGENTS.md (non-interactive) -fastskill sync --yes - -# Or run interactively to choose which skills to expose -fastskill sync -``` - -### 2. Optional: Skill indexing and search +# 1. Install the skills declared in skill-project.toml +fastskill install -For semantic search over skills, index the skills directory: +# 2. Verify what is on disk +fastskill list -```bash +# 3. (Optional) Build the local index for semantic search fastskill reindex --skills-dir .claude/skills/ ``` -### 3. MCP Registration +## MCP registration Register `fastskill` as an MCP server inside Cursor with a single command: @@ -49,285 +40,108 @@ fastskill mcp install --agent cursor --stdio --scope project --overwrite fastskill mcp install --agent cursor --stdio --dry-run ``` -After running the command, reload Cursor. The tools exposed by `fastskill mcp serve --transport stdio` will be callable from the agent. - -> **Deprecated:** Manually editing `.cursor/mcp.json` to add a `fastskill` MCP entry is deprecated. Use `fastskill mcp install` instead. - -### 4. Cursor integration - -Cursor reads AGENTS.md and native skills/agents configuration to discover available skills. - -## Configuration - -### Basic setup - -Ensure your project has a `skill-project.toml` with `[tool.fastskill]` and a `skills_directory`. Then run: - -```bash -fastskill sync --yes -``` - -This updates AGENTS.md with the list of installed skills so Cursor (and other agents) can discover them. Use `fastskill sync` without `--yes` to choose which skills to expose interactively. - -## AGENTS.md format +After running the command, reload Cursor. The tools exposed by +`fastskill mcp serve --transport stdio` will be callable from the agent. -`fastskill sync` writes a `` section into the detected metadata file -(AGENTS.md for Cursor) with `` listing each skill's id, description, and location (project or global). Cursor and other agents that read AGENTS.md use this to discover and invoke skills (e.g. via `fastskill read `). +> **Deprecated:** Manually editing `.cursor/mcp.json` to add a `fastskill` MCP entry is +> deprecated. Use `fastskill mcp install` instead. ## How Cursor uses the skills -### Tool discovery - When you ask Cursor to perform a task, it: -1. **Reads available skills** from AGENTS.md (Cursor's instruction file) and native Cursor skills/agents -2. **Matches task requirements** against skill descriptions -3. **Identifies relevant skills** for the task -4. **Provides access** to the full SKILL.md content via `fastskill read ` - -### Example Usage +1. **Reads available skills** from the skills directory (and the FastSkill MCP server, if + registered). +2. **Matches task requirements** against each skill's `description` frontmatter. +3. **Loads the full `SKILL.md`** for relevant skills to get instructions and parameters — + the same content `fastskill read ` prints. -**User Query:** *"Help me create a PowerPoint presentation for my quarterly review"* +### Example -**Cursor Process:** -1. Scans skills registry for "presentation" or "powerpoint" related skills -2. Finds relevant skills (pptx, presentation-tools, etc.) -3. Accesses full SKILL.md content for implementation details -4. Provides step-by-step guidance using the skill +**User query:** *"Help me create a PowerPoint presentation for my quarterly review."* -### Context Awareness +Cursor scans installed skills for presentation-related descriptions, finds a match (e.g. +`pptx`), loads its `SKILL.md`, and follows the skill's instructions to complete the task. -Cursor can now understand: -- **Available tools**: What skills are installed -- **Skill capabilities**: What each skill can do -- **Usage patterns**: How to combine multiple skills -- **Implementation details**: Specific instructions and parameters - -## Advanced Configuration - -### Agent detection - -`fastskill sync` automatically detects which metadata file to use by scanning the project -directory for known files in this order: AGENTS.md, CLAUDE.md, GEMINI.md. The first -file found is used. If none exist, AGENTS.md is created. - -| Agent | Metadata file | Agent key | -|---|---|---| -| Cursor | AGENTS.md | `cursor-agent` | -| Claude Code | CLAUDE.md | `claude` | -| Google Gemini | GEMINI.md | `gemini` | -| GitHub Copilot | *(unsupported — use `--agents-file`)* | `copilot` | - -To target Cursor explicitly regardless of what files exist: - -```bash -fastskill sync --yes --agent cursor-agent -``` +## Configuration -To write to a completely custom path: +Ensure your project has a `skill-project.toml` and that Cursor and FastSkill agree on the +skills directory. The default is `.claude/skills/`; override it via `skills_directory` in +`.fastskill/config.yaml` or the `--skills-dir` flag. ```bash -fastskill sync --yes --agents-file custom.md +fastskill install +fastskill list ``` -### Multiple Skill Directories +### Multiple skill directories ```bash -# Index multiple directories fastskill reindex --skills-dir .claude/skills/ fastskill reindex --skills-dir ./custom-skills/ - -# Or use different output files -# Configure separate exports for each directory ``` -### Choosing which skills to sync - -Run `fastskill sync` without `--yes` to interactively select which installed skills appear -in the detected metadata file. - ## Automation -### GitHub Actions - -Update skills metadata when skills change: +Keep the skills directory reconciled in CI so commits always carry the resolved skill set: ```yaml -# .github/workflows/update-skills.yml -name: Update skills metadata +# .github/workflows/reconcile-skills.yml +name: Reconcile skills on: push: paths: - - '.claude/skills/**' - 'skill-project.toml' + - 'skills.lock' jobs: - update-agents: + install-skills: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - name: Install FastSkill CLI run: | # Add the steps your org uses to place `fastskill` on PATH (release tarball, package, etc.) fastskill -V - - - name: Sync skills to metadata file - run: fastskill sync --agent cursor-agent --yes - - - name: Commit metadata file - run: | - git config --global user.name 'github-actions[bot]' - git config --global user.email 'github-actions[bot]@users.noreply.github.com' - git add AGENTS.md - git commit -m 'chore: update AGENTS.md skills' || echo "No changes" - git push -``` - -### Pre-commit hooks - -```bash -#!/bin/bash -# .git/hooks/pre-commit -if git diff --cached --name-only | grep -q ".claude/skills/"; then - echo "Skills changed, syncing metadata file..." - fastskill sync --agent cursor-agent --yes - git add AGENTS.md -fi + - name: Install skills from lock + run: fastskill install --lock + - name: Verify + run: fastskill list ``` ## Troubleshooting -### Common Issues - -#### AGENTS.md not updated -```bash -# Ensure skill-project.toml and skills directory exist -cat skill-project.toml -ls -la .claude/skills/ # or your configured skills_directory - -# Sync manually -fastskill sync --yes -``` +**Cursor doesn't see a skill** -#### Cursor not recognizing skills ```bash -# Ensure AGENTS.md exists and contains a skills section -cat AGENTS.md | head -80 +# Confirm it is installed and reconciled +fastskill list -# Re-sync installed skills -fastskill sync --yes +# Confirm its content is readable +fastskill read ``` -#### Outdated skill list -```bash -fastskill sync --yes -``` - -### Debug Commands +**Semantic search returns nothing** ```bash -# Check FastSkill configuration -fastskill --help - -# Test search functionality -fastskill search "test query" --embedding false - -# Verify index exists -ls -la .claude/skills/.fastskill/index.db +# Reindex (requires an embedding provider; see `fastskill doctor`) +fastskill reindex --skills-dir .claude/skills/ -# Check detected metadata file -wc -l AGENTS.md +# Keyword fallback works without a provider +fastskill search "test query" --local --embedding false ``` -## Performance Considerations - -### File Size - -- **Small repositories**: < 10KB -- **Medium repositories**: 50-200KB -- **Large repositories**: 500KB+ - -### Generation Time - -- **Small**: < 5 seconds -- **Medium**: 10-30 seconds -- **Large**: 1-5 minutes - -### Update Frequency - -- **On-demand**: Update when skills change -- **Scheduled**: Daily/weekly regeneration -- **Event-driven**: Update on git push to skills directory - -## Integration Patterns - -### Multi-environment setup - -Use different files per environment via `--agents-file`: +**Check environment readiness** ```bash -fastskill sync --yes --agents-file AGENTS-dev.md -fastskill sync --yes --agents-file AGENTS-prod.md -``` - -### Team Collaboration - -Share skills registry across team: - -```yaml -# Generate team-wide registry -markdown_export: - output_path: "docs/team-skills.md" - header_instructions: | - Team Skills Registry - Updated $(date) - This file contains all skills available to the development team. -``` - -### Documentation Integration - -Include in project docs: - -```yaml -# Generate for docs site -markdown_export: - output_path: "docs/skills/index.md" - header_instructions: | - # Available Skills - - This page lists all skills available in the project. -``` - -## Future Enhancements - -### Planned Features - -- **Filtered exports**: Export only skills relevant to specific projects -- **Version tracking**: Track skill versions and changes -- **Dependency mapping**: Show skill relationships and dependencies -- **Usage analytics**: Track which skills are most used -- **Collaborative editing**: Allow team members to contribute skill updates - -### Custom Templates - -Allow custom markdown templates: - -```yaml -markdown_export: - template: "custom-template.md" - variables: - project_name: "My Project" - team: "Engineering" +fastskill doctor ``` ## Summary FastSkill's Cursor integration provides: -✅ **Automatic skill discovery** for AI agents -✅ **Seamless integration** with existing workflows -✅ **Up-to-date documentation** through automated generation -✅ **Performance optimized** for large skill repositories -✅ **Flexible configuration** for different use cases - -The integration bridges the gap between static skill definitions and dynamic AI agent capabilities, enabling Cursor to provide more intelligent and context-aware assistance. +- **Direct skill discovery** — Cursor reads installed skills from the skills directory, no sync step +- **MCP access** — register the FastSkill MCP server for tool-based access inside Cursor +- **Reproducible installs** — `skill-project.toml` + `skills.lock` keep the skill set consistent across the team +- **Optional semantic search** — `fastskill reindex` + `fastskill search --local` when an embedding provider is configured diff --git a/webdocs/optimize/results.mdx b/webdocs/optimize/results.mdx index 7891b24..d60cebf 100644 --- a/webdocs/optimize/results.mdx +++ b/webdocs/optimize/results.mdx @@ -120,7 +120,7 @@ Top-level run files: | File | Description | |---|---| -| `skillopt.toml` | Provenance copy of the config used for this run | +| `optimize.toml` | Provenance copy of the config used for this run | | `runtime_state.json` | Current best score, epoch, global step (updated live) | | `history.json` | Array of step records: step index, accepted, scores, tokens | | `best_skill.md` | The best skill document seen across all accepted steps | diff --git a/webdocs/optimize/running.mdx b/webdocs/optimize/running.mdx index e1fb57b..3f5bb8f 100644 --- a/webdocs/optimize/running.mdx +++ b/webdocs/optimize/running.mdx @@ -85,7 +85,7 @@ Re-reads and re-prints every ~2 seconds until the run completes. fastskill optimize resume .skillopt/runs/2026-06-03T14-22-01Z ``` -The `resume` subcommand reads the stored `skillopt.toml` copy from the run directory (saved at run-start for provenance), re-validates it against the current files, and calls the training loop at the last checkpoint. +The `resume` subcommand reads the stored `optimize.toml` copy from the run directory (saved at run-start for provenance; legacy run directories from before the rename may instead contain `skillopt.toml`, which is still read for backward compatibility), re-validates it against the current files, and calls the training loop at the last checkpoint. **Note:** Resume uses the config stored *inside* the run directory, not your original config file. This ensures the run is reproducible regardless of changes you may have made to the config since starting. @@ -118,7 +118,7 @@ Every run creates a self-contained directory: ``` .skillopt/runs/2026-06-03T14-22-01Z/ -├── skillopt.toml # stored config (provenance copy) +├── optimize.toml # stored config (provenance copy) ├── runtime_state.json # live state: best_score, epoch, global_step ├── history.json # array of step records ├── best_skill.md # best skill document seen so far diff --git a/webdocs/skill-management/manifest-system.mdx b/webdocs/skill-management/manifest-system.mdx index 38b364d..5e15148 100644 --- a/webdocs/skill-management/manifest-system.mdx +++ b/webdocs/skill-management/manifest-system.mdx @@ -405,7 +405,7 @@ If you see version conflicts: ```bash # Check what's installed -fastskill show +fastskill list # Update to resolve conflicts fastskill update diff --git a/webdocs/skill-management/validation.mdx b/webdocs/skill-management/validation.mdx index e89334e..4ac08e1 100644 --- a/webdocs/skill-management/validation.mdx +++ b/webdocs/skill-management/validation.mdx @@ -121,7 +121,7 @@ Fix issues and try again. ```bash fastskill list -fastskill show +fastskill read --meta ``` If you use automation, run the same commands after `fastskill install` or `fastskill install --lock` so broken skills fail the job early. See [CI/CD integration](/integration/cicd-pipelines) for runner outlines without repository-specific install paths. diff --git a/webdocs/welcome.mdx b/webdocs/welcome.mdx index b6e547a..c730336 100644 --- a/webdocs/welcome.mdx +++ b/webdocs/welcome.mdx @@ -5,7 +5,7 @@ description: "Package manager and operational toolkit for Agent AI Skills. Disco # Welcome to FastSkill -**Package manager and operational toolkit for Agent AI Skills.** FastSkill enables discovery, installation, versioning, and deployment of skills at scale. It follows the Claude Code skill layout (`SKILL.md`) and adds manifests, lockfiles, validation, optional eval suites, search, and agent sync so teams can **operate** skills—not only host a catalog. +**Package manager and operational toolkit for Agent AI Skills.** FastSkill enables discovery, installation, versioning, and deployment of skills at scale. It follows the Claude Code skill layout (`SKILL.md`) and adds manifests, lockfiles, validation, optional eval suites, and search so teams can **operate** skills—not only host a catalog. ## The Problem We're Solving @@ -59,9 +59,9 @@ fastskill init # Skill author: create skill-project metadata fastskill add ./my-skill -e # Add or link a skill (editable when local) fastskill install --without dev # Install manifest without dev-only groups fastskill update # Move pinned versions forward when you choose -fastskill show --tree # Inspect what is installed +fastskill read my-skill --tree # Inspect a skill and its dependency tree fastskill eval validate # Check eval config and prompts (optional) -fastskill sync --yes # Write installed skills to agent metadata +fastskill doctor # Diagnose configuration and environment ``` ### Dependency management @@ -134,11 +134,11 @@ FastSkill builds on the **Anthropic Claude Code skill standard** (`SKILL.md`) an - **Reconciliation**: `fastskill list` compares manifest, lock, and disk (see [Skill validation](/skill-management/validation)) - **Eval suites**: `fastskill eval` for validate / run / report / score against defined cases ([eval command](/cli-reference/eval-command)) -### 3. **Discovery & agent sync** +### 3. **Discovery** - **Search**: remote catalogs by default; `--local` for installed skills and embeddings -- **Read & show**: inspect what agents will load -- **Sync**: push the installed set into agent metadata files (`fastskill sync`) +- **Read**: inspect what agents will load — full content, or `--meta`/`--tree` for metadata and dependencies +- **Direct discovery**: agents read installed skills straight from the skills directory; no metadata-file sync step ### 4. **Publish & registries** (when you distribute) @@ -274,8 +274,8 @@ FastSkill focuses on **repeatable operations** for AI agent skills: ## What's Next? - [Manifest system](/skill-management/manifest-system) for `skill-project.toml`, locks, and how installs resolve -- [CLI reference](/cli-reference/overview) and [tooling commands](/cli-reference/tooling-commands) (`sync`, `analyze`, …) -- [Cursor integration](/integration/cursor-integration) for metadata files in the editor +- [CLI reference](/cli-reference/overview) and [tooling commands](/cli-reference/tooling-commands) (`doctor`, `analyze`, …) +- [Cursor integration](/integration/cursor-integration) for using installed skills in the editor - [Registry overview](/registry/overview) when you are ready to publish or browse catalogs ---