diff --git a/webdocs/MIGRATION.md b/webdocs/MIGRATION.md new file mode 100644 index 00000000..88a6ae28 --- /dev/null +++ b/webdocs/MIGRATION.md @@ -0,0 +1,59 @@ +# Fumadocs Migration Notes + +This directory contains documentation content converted from Mintlify to [Fumadocs](https://fumadocs.dev) MDX format. + +## What changed + +### Navigation: mint.json → meta.json + +Mintlify's central `mint.json` was replaced with per-folder `meta.json` files. Fumadocs derives the sidebar from the folder structure plus `meta.json` ordering. The root `meta.json` uses `---Separator---` entries to recreate the original navigation groups (Getting Started, Configuration, Skill Management, etc.). + +### Component mappings + +| Mintlify | Fumadocs | Notes | +|----------|----------|-------| +| `` | `` | Default type (info) | +| `` | `` | | +| `` | `` | | +| `` | `` | Mapped to default (info) | +| `` | `` | | +| `` / `` | `` / `` | `icon` props stripped (string names need JSX components in host app) | +| `` / `` | `` / `` | Slugified `id` added | +| `` / `` | `### X [step]` headings | Requires `remark-steps` plugin in host app | +| `` / `` | `` / `` | | +| `` | `#### \`field\` (type, required/optional)` | Converted to heading + bullets | +| `` | removed | Content (images) kept | + +### Other changes + +- `TROUBLESHOOTING.md` renamed to `troubleshooting.mdx` for slug consistency. +- Fixed duplicate `` in `skill-management/validation.mdx`. +- Card `icon="..."` props were stripped. Fumadocs requires JSX icon components (e.g. `lucide-react`), not string names. Add icons in the host app via the `icon` handler on `loader()` or per-card. + +## What the hosting app needs to do + +This migration covers content only. To serve these docs: + +1. **Create a fumadocs app** (Next.js recommended): `pnpm create fumadocs-app` +2. **Point content source at this directory**: set `dir: 'content/docs'` (or wherever you place these files) in `source.config.ts` → `defineDocs()`. +3. **Enable remark-steps**: the `[step]` heading markers require the `remark-steps` plugin. Add it to `mdxOptions` in `source.config.ts`. +4. **Place static assets in `public/`**: images referenced as `/images/...` and logos in `/logo/` must live in the host app's `public/` directory. +5. **Configure theme and search**: colors, logo, topbar CTA, and search (Algolia/Orama) are host-app concerns, not content-level config. +6. **Map card icons** (optional): if you want icons on cards, pass an `icon` handler to `loader()` that resolves icon names to `lucide-react` components. + +### File structure + +``` +webdocs/ + meta.json ← root navigation (groups + ordering) + index.mdx ← landing page + welcome.mdx + quickstart.mdx + ... + cli-reference/ + meta.json ← folder page ordering + overview.mdx + ... + images/ ← static assets (move to public/ in host app) + logo/ ← logo SVGs (move to public/ in host app) +``` diff --git a/webdocs/cheatsheet.mdx b/webdocs/cheatsheet.mdx index 9afe627d..80e10b9b 100644 --- a/webdocs/cheatsheet.mdx +++ b/webdocs/cheatsheet.mdx @@ -51,9 +51,9 @@ Quick reference for common FastSkill operations, ordered from everyday manifest | 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/discovery-commands.mdx b/webdocs/cli-reference/discovery-commands.mdx index b8fbf902..b3f962db 100644 --- a/webdocs/cli-reference/discovery-commands.mdx +++ b/webdocs/cli-reference/discovery-commands.mdx @@ -7,15 +7,15 @@ description: "FastSkill CLI commands for skill search, vector indexing, and repo Discovery commands help you find, index, and manage skills in your FastSkill ecosystem. These commands provide semantic search, vector indexing, and repository management capabilities. - + **Command Architecture**: - **Repository Management**: Use `fastskill repos` for all repository operations (add, remove, list, test, refresh) and catalog browsing (skills, show, versions) - **Skill Discovery**: Use `fastskill search` (remote catalogs by default; add `--local` for installed skills and embeddings) - + - + For detailed documentation on specific commands, see the dedicated command pages linked below. - + ## Command Reference @@ -23,9 +23,9 @@ For detailed documentation on specific commands, see the dedicated command pages Query skills. **Default scope is remote** (catalog APIs). Use `--local` to search installed skills; local embedding search uses OpenAI when configured and respects `--embedding`. - + See [search Command](/cli-reference/search-command) for complete documentation with output formats. - + ```bash # Remote catalog search (default) @@ -64,9 +64,9 @@ fastskill search "process text" --repository my-repo Rebuild the vector search index by scanning all installed skills. Updates embeddings and similarity database. - + See [reindex Command](/cli-reference/reindex-command) for complete documentation with concurrency options. - + ```bash # Reindex all skills (uses configured skills directory) @@ -105,9 +105,9 @@ fastskill reindex --skills-dir ./.claude/skills Manage skill repositories for discovering and installing skills. Supports multiple repository types with authentication and priority-based resolution. This is the **primary command** for repository management and catalog browsing. - + See [repos Command](/cli-reference/repository-command) for complete documentation with subcommands and authentication. - + ```bash # List all configured repositories @@ -196,9 +196,9 @@ When skills are available in multiple repositories, priority determines the orde - Default priority: 0 - Higher priority values are checked later - + **Legacy commands**: `sources` (alias `source`) and `registry` are hidden from `fastskill --help` but still exist for compatibility. Prefer `fastskill repos` for repository and catalog operations. - + ## Search and Reindex Workflow @@ -270,77 +270,75 @@ fastskill search "skill name or description" ## Troubleshooting - - - + + + **Index not built**: Make sure you've run `fastskill reindex` after installing skills. - + - + **Query too specific**: Try broader terms or different phrasing. - + - + **Skills not installed**: Verify skills are in `.claude/skills/` with `fastskill list`. - + - - + + **OpenAI API key not set**: Set `OPENAI_API_KEY` environment variable. ```bash export OPENAI_API_KEY="your-key-here" fastskill reindex ``` - + - + **API rate limit errors**: Reduce concurrent requests with `--max-concurrent 3`. - + - + **Network errors**: Check internet connectivity and OpenAI API status. - + - - + + **Invalid repository name**: Check repository name with `fastskill repos list`. - + - + **Repository URL incorrect**: Verify URL is accessible with `fastskill repos test `. - + - + **Authentication failed**: Verify authentication type and credentials with `fastskill repos info `. - + - + ## Best Practices - - - Always run `fastskill reindex` after installing, updating, or modifying skills to keep search index current. - +### 1. Reindex after changes - - Search queries work best with natural language that matches skill descriptions in SKILL.md files. - +Always run `fastskill reindex` after installing, updating, or modifying skills to keep search index current. - - Set lower priority numbers for primary repositories to ensure preferred skills are discovered first. - +### 2. Use natural language queries - - Use `fastskill repos test ` to verify repositories are accessible before using them. - +Search queries work best with natural language that matches skill descriptions in SKILL.md files. - - Use `--max-concurrent` to balance speed and API rate limits. Start with default and adjust based on rate limit errors. - - +### 3. Organize repositories by priority + +Set lower priority numbers for primary repositories to ensure preferred skills are discovered first. + +### 4. Test repositories after configuration + +Use `fastskill repos test ` to verify repositories are accessible before using them. + +### 5. Control API concurrency for reindexing + +Use `--max-concurrent` to balance speed and API rate limits. Start with default and adjust based on rate limit errors. ## See Also diff --git a/webdocs/cli-reference/eval-command.mdx b/webdocs/cli-reference/eval-command.mdx index 3ce9a34e..0c4b7d6a 100644 --- a/webdocs/cli-reference/eval-command.mdx +++ b/webdocs/cli-reference/eval-command.mdx @@ -7,9 +7,9 @@ description: "Validate, run, report, and score skill evaluation suites defined i `fastskill eval` runs skill quality checks using prompts and rubrics under `[tool.fastskill.eval]` in `skill-project.toml`. Subcommands are `validate`, `run`, `report`, and `score`. - + `eval run` requires an agent on `PATH` for the chosen `--agent` key (for example `codex`, `claude`, `gemini`, `opencode`, or `agent`). Use `eval validate --agent ` to verify availability. - + ## Usage diff --git a/webdocs/cli-reference/init-command.mdx b/webdocs/cli-reference/init-command.mdx index 445f7cc5..3dd52f7d 100644 --- a/webdocs/cli-reference/init-command.mdx +++ b/webdocs/cli-reference/init-command.mdx @@ -68,9 +68,9 @@ Overwrite existing `skill-project.toml`: fastskill init --force ``` - + Using `--force` will overwrite your existing `skill-project.toml` file. Make sure to backup if you need to preserve any custom configurations. - + ## Behavior @@ -133,9 +133,9 @@ fastskill init # Creates: [metadata] id = "my-skill" ``` - + If you're in a project directory (no SKILL.md), the `skill-project.toml` can still be used to declare dependencies for installation via `fastskill install`. - + ## Context Detection @@ -191,9 +191,9 @@ license: MIT Skill content here... ``` - + If you provide `--version`, `--description`, or `--author` flags, they will override the values from SKILL.md frontmatter. - + ## Version Validation diff --git a/webdocs/cli-reference/install-command.mdx b/webdocs/cli-reference/install-command.mdx index b9c8f80b..4291cd35 100644 --- a/webdocs/cli-reference/install-command.mdx +++ b/webdocs/cli-reference/install-command.mdx @@ -45,9 +45,9 @@ Install production skills only, excluding dev group: fastskill install --without dev ``` - + This is useful for CI/CD pipelines where you want lean production deployments without development dependencies. - + ### Install Only Specific Groups @@ -72,9 +72,9 @@ Install exact versions from `skills.lock`: fastskill install --lock ``` - + Use `--lock` for production deployments to ensure you install the exact same versions that were used in development. - + ### Combined Example: Production Deployment @@ -120,9 +120,9 @@ test-helper = { source = "git", url = "https://github.com/user/test-helper.git", mock-skill = { source = "registry", id = "mock-skill", groups = ["test"] } ``` - + If no `groups` are specified, the skill belongs to no groups and will always be installed. - + ### Default Group Behavior @@ -446,27 +446,25 @@ jobs: ## Best Practices - - - Always commit both files to version control. This ensures all team members install the same versions. - +### 1. Commit both skill-project.toml and skills.lock - - Separate dev, test, and production dependencies into groups. Use `--without dev` for production builds. - +Always commit both files to version control. This ensures all team members install the same versions. - - Run `fastskill install` after modifying `skill-project.toml` to update `skills.lock` with new versions. - +### 2. Use groups for environment-specific dependencies - - Always use `--lock` flag in production to ensure exact version matches. - +Separate dev, test, and production dependencies into groups. Use `--without dev` for production builds. - - Run `fastskill reindex` after installation to update the semantic search index. - - +### 3. Run fastskill install before committing + +Run `fastskill install` after modifying `skill-project.toml` to update `skills.lock` with new versions. + +### 4. Use --lock for production deployments + +Always use `--lock` flag in production to ensure exact version matches. + +### 5. Reindex after installation + +Run `fastskill reindex` after installation to update the semantic search index. ## See Also diff --git a/webdocs/cli-reference/meta.json b/webdocs/cli-reference/meta.json new file mode 100644 index 00000000..dd919bf7 --- /dev/null +++ b/webdocs/cli-reference/meta.json @@ -0,0 +1,16 @@ +{ + "pages": [ + "overview", + "skill-commands", + "discovery-commands", + "init-command", + "install-command", + "update-command", + "reindex-command", + "search-command", + "serve-command", + "repository-command", + "eval-command", + "tooling-commands" + ] +} diff --git a/webdocs/cli-reference/overview.mdx b/webdocs/cli-reference/overview.mdx index 36219d03..e28f956b 100644 --- a/webdocs/cli-reference/overview.mdx +++ b/webdocs/cli-reference/overview.mdx @@ -7,9 +7,9 @@ description: "CLI for the FastSkill package manager: installs, manifests, valida The FastSkill CLI is how you **install and operate** skills: manifests and `skills.lock`, validation and `fastskill eval`, search, plus `serve` when you want a local HTTP surface. - + The CLI supports both interactive and scripting use cases, with comprehensive help text and validation for all commands. - + ## Installation @@ -25,23 +25,21 @@ For Git-based skill sources, use a build that includes Git support if your distr ### Get Help - - +### 1. General help + ```bash fastskill --help ``` This shows all available commands and global options. - - +### 2. Command-specific help + ```bash fastskill serve --help # Help for serve command fastskill add --help # Help for add command fastskill list --help # Help for list command ``` - - ### Global Options @@ -58,68 +56,68 @@ fastskill list --help # Help for list command ### Project and lifecycle - - + + Create `skill-project.toml` for a skill (authors). See [init Command](/cli-reference/init-command). - + Install skills from `skill-project.toml` (supports groups and `--lock`). See [install Command](/cli-reference/install-command). - + Update skills to latest from source with version strategies. See [update Command](/cli-reference/update-command). - + Rebuild the search index for semantic discovery. See [reindex Command](/cli-reference/reindex-command). - + Start the HTTP server (`--host`, `--port`). Web UI and API routes are served with the process. See [serve Command](/cli-reference/serve-command). - + ### Skills - - + + Add skills from registry ID, git, zip, or local folder (supports `-r` for recursive folder add, `--branch`, `--tag`, `-e`, `--group`). See [skill commands](/cli-reference/skill-commands#add). - + Retrieve skill documentation and base directory path in agent-optimized format. See [skill commands](/cli-reference/skill-commands#fastskill-read). - + List locally installed skills with reconciliation status (supports `--format table|json|grid|xml`, `--json`). See [skill commands](/cli-reference/skill-commands#list). - + Remove skills by ID. See [skill commands](/cli-reference/skill-commands#fastskill-remove). - + ### Registry & search - - + + Search remote catalogs by default; use `--local` for embedding search on installed skills. See [search Command](/cli-reference/search-command). - + Manage repositories (list/add/remove/info/update/test/refresh) and browse remote skill catalog with authentication and priority. See [repos Command](/cli-reference/repository-command). - + ### Diagnostics and tooling - - + + Show CLI version. - + Validate and run skill evaluation suites. See [eval Command](/cli-reference/eval-command). - + Similarity matrix, clusters, duplicates. See [tooling commands](/cli-reference/tooling-commands#fastskill-analyze). - + Check environment readiness (skills directory, embedding provider, auth). See [tooling commands](/cli-reference/tooling-commands#fastskill-doctor). - + ## Version Command @@ -265,34 +263,34 @@ For running `fastskill` in automation (build machines, sandboxes), install the C ### Common Issues - - - + + + **Path issue**: Ensure FastSkill is installed and in your PATH. ```bash which fastskill fastskill -V ``` - + - - + + **File permissions**: Ensure you have read/write permissions for skill directories. ```bash # Fix permissions chmod 755 ./skills/ chmod 644 ./skills/*.json ``` - + - + **Service permissions**: Run with appropriate privileges for system-wide operations. - + - - + + **Port conflicts**: Check if the default port (8080) is available. ```bash # Check port usage @@ -301,9 +299,9 @@ For running `fastskill` in automation (build machines, sandboxes), install the C # Use different port fastskill serve --port 9000 ``` - + - + ### More verbose output @@ -315,28 +313,26 @@ Some distributions document extra logging variables; check your install notes if ## Best Practices - - - Commit `skill-project.toml` and `skills.lock` together for reproducible installs. - +### 1. Commit manifest and lock + +Commit `skill-project.toml` and `skills.lock` together for reproducible installs. + +### 2. Reindex after changes + +Run `fastskill reindex` after adding or updating skills so search stays fresh. + +### 3. Use groups for optional skills + +Use groups (for example `--group dev`) and install with `--without dev` when you want a smaller production skill set. - - Run `fastskill reindex` after adding or updating skills so search stays fresh. - +### 4. Check the server when you use serve - - Use groups (for example `--group dev`) and install with `--without dev` when you want a smaller production skill set. - +Confirm `http://:/` responds after upgrades or config changes. - - Confirm `http://:/` responds after upgrades or config changes. - +### 5. Back up manifests before big changes - - Keep copies of `skill-project.toml`, `skills.lock`, and any custom `.fastskill` config before bulk edits. - - +Keep copies of `skill-project.toml`, `skills.lock`, and any custom `.fastskill` config before bulk edits. - + Commands can change installed skills and manifest files. Try changes on a copy of the project or a branch first if you are unsure. - + diff --git a/webdocs/cli-reference/reindex-command.mdx b/webdocs/cli-reference/reindex-command.mdx index a9b3767f..71cbaf1b 100644 --- a/webdocs/cli-reference/reindex-command.mdx +++ b/webdocs/cli-reference/reindex-command.mdx @@ -7,9 +7,9 @@ description: "Index skills with embeddings for semantic search capabilities." The `reindex` command scans skill directories, extracts metadata from SKILL.md files, generates embeddings using OpenAI's API, and builds a local vector index for semantic search. - + This command requires OpenAI API configuration and will create a local SQLite database to store embeddings. - + ## Basic Usage @@ -19,7 +19,7 @@ fastskill reindex --skills-dir /path/to/skills/ ## Command Options -### --skills-dir +### --skills-dir `<DIRECTORY>` Optional override for the skills root (otherwise the CLI uses the same discovery as other commands, typically from `skill-project.toml`). @@ -45,7 +45,7 @@ fastskill reindex --skills-dir .claude/skills/ --force - When embeddings seem outdated - To rebuild corrupted index -### --max-concurrent +### --max-concurrent `<NUMBER>` Control the number of concurrent embedding API requests (default: 5). diff --git a/webdocs/cli-reference/repository-command.mdx b/webdocs/cli-reference/repository-command.mdx index 55b8e1d7..4d0d016b 100644 --- a/webdocs/cli-reference/repository-command.mdx +++ b/webdocs/cli-reference/repository-command.mdx @@ -7,9 +7,9 @@ description: "Manage skill repositories and browse the remote catalog with fasts Manage skill repositories and browse remote skill catalog. - + The `repos` command is the primary interface for repository management and catalog browsing in FastSkill. Use `fastskill search` for semantic search of installed skills. - + ## Usage @@ -487,18 +487,18 @@ git push -u origin main ### Troubleshooting - - - + + + **Check name**: Ensure the repository name matches what you added. ```bash fastskill repos list ``` - + - - + + **Verify credentials**: ```bash # Check environment variable @@ -510,23 +510,23 @@ git push -u origin main # Test basic auth credentials curl -u username:password https://api.example.com/health ``` - + - - + + **Verify priority values**: Lower numbers have higher priority. ```bash fastskill repos list ``` Priority 0 is highest, priority 10 is lower. - + - + - + Repositories configuration is stored in `skill-project.toml` and should be committed to version control. Authentication credentials (environment variables) should never be committed. - + ## See Also diff --git a/webdocs/cli-reference/search-command.mdx b/webdocs/cli-reference/search-command.mdx index 0fe0f813..3f3e8d47 100644 --- a/webdocs/cli-reference/search-command.mdx +++ b/webdocs/cli-reference/search-command.mdx @@ -9,9 +9,9 @@ description: "Search for skills using semantic embeddings or traditional keyword With `--local`, the command searches **installed skills** in your configured skills directory. Local mode supports embedding search (`--embedding true|false|auto`), which requires `fastskill reindex` and embedding configuration when not using keyword-only mode. - + Run `fastskill search --help` for the authoritative flag list. - + ## Basic Usage @@ -39,7 +39,7 @@ fastskill search "powerpoint" --local --skills-dir ./.claude/skills ## Command Options -### --limit +### --limit `<NUMBER>` Maximum number of results to return: @@ -74,7 +74,7 @@ fastskill search "query" --remote # explicit remote (default without --l fastskill search "query" --repository r # remote, single repo ``` -### --embedding +### --embedding `<true|false|auto>` **Only applies when `--local` is set**; ignored for remote search. diff --git a/webdocs/cli-reference/skill-commands.mdx b/webdocs/cli-reference/skill-commands.mdx index 4e87cc9a..0a576208 100644 --- a/webdocs/cli-reference/skill-commands.mdx +++ b/webdocs/cli-reference/skill-commands.mdx @@ -7,9 +7,9 @@ description: "FastSkill CLI commands for skill management including registration Skill commands provide comprehensive management of FastSkill skills through command line interface. These commands allow you to register, install, update, remove, and manage skills in your FastSkill ecosystem. - + For detailed documentation on specific commands, see the dedicated command pages linked below. - + ## Command Reference @@ -17,9 +17,9 @@ For detailed documentation on specific commands, see the dedicated command pages Initialize `skill-project.toml` for skill authors in current skill directory. This command extracts metadata from `SKILL.md` frontmatter and prompts for additional fields to create a comprehensive metadata file. - + See [init Command](/cli-reference/init-command) for complete documentation with all flags and examples. - + ```bash # Create skill-project.toml interactively @@ -132,9 +132,9 @@ You can also run `fastskill ` with no subcommand; it routes to the sam Install skills from `skill-project.toml` to skills storage directory (like `poetry install`). The storage location is configured in `.fastskill/config.yaml` via `skills_directory` (default: `.claude/skills/`). - + See [install Command](/cli-reference/install-command) for complete documentation with groups, lockfile, and reconciliation features. - + ```bash # Install all skills from skill-project.toml @@ -159,9 +159,9 @@ fastskill install --lock Update skills in skills storage directory to their latest versions from source. The storage location is configured in `.fastskill/config.yaml` via `skills_directory` (default: `.claude/skills/`). - + See [update Command](/cli-reference/update-command) for complete documentation with strategies and version constraints. - + ```bash # Update all skills @@ -209,9 +209,9 @@ fastskill read my-skill-id --meta --json fastskill list ``` - + `fastskill show` has been removed. Use `fastskill read --meta` to view skill metadata or `fastskill list` to enumerate all installed skills. - + ### fastskill add @@ -401,6 +401,6 @@ fastskill doctor fastskill list ``` - + Skill commands support both interactive use and automation. Use appropriate options for your workflow. Reindex runs automatically after `add`/`install`/`update`/`remove` when an embedding provider is configured; use `--no-reindex` to suppress or `fastskill doctor` to check environment readiness. - + diff --git a/webdocs/cli-reference/tooling-commands.mdx b/webdocs/cli-reference/tooling-commands.mdx index 1d3b8b21..f350c1de 100644 --- a/webdocs/cli-reference/tooling-commands.mdx +++ b/webdocs/cli-reference/tooling-commands.mdx @@ -3,9 +3,9 @@ title: "Marketplace, analyze, and doctor" description: "CLI reference for fastskill marketplace, fastskill analyze, and fastskill doctor." --- - + `fastskill sync` has been removed. Agents read the skills directory directly; no metadata-file sync is needed. - + ## fastskill marketplace diff --git a/webdocs/cli-reference/update-command.mdx b/webdocs/cli-reference/update-command.mdx index 38a9e04e..91ca20fa 100644 --- a/webdocs/cli-reference/update-command.mdx +++ b/webdocs/cli-reference/update-command.mdx @@ -56,9 +56,9 @@ Check which skills have updates available without installing: fastskill update --check ``` - + Use `--check` to see what's available before updating. Useful for reviewing changes before applying them. - + ### Dry Run @@ -493,30 +493,28 @@ Updating data-processor... ## Best Practices - - - Use `fastskill update --check` to see what's available before applying updates. Review changes, especially for major version bumps. - +### 1. Check before updating - - - Use `--strategy patch` for bug fixes only +Use `fastskill update --check` to see what's available before applying updates. Review changes, especially for major version bumps. + +### 2. Use appropriate strategies + +- Use `--strategy patch` for bug fixes only - Use `--strategy minor` for new features without breaking changes - Use `--strategy major` when you're ready for breaking changes - Use `--strategy latest` for bleeding edge (not recommended for production) - - - Always run `fastskill reindex` after updating skills to keep search index current. - +### 3. Reindex after updates + +Always run `fastskill reindex` after updating skills to keep search index current. + +### 4. Commit lockfile after updates + +Commit `skills.lock` after successful updates to track version changes in version control. - - Commit `skills.lock` after successful updates to track version changes in version control. - +### 5. Test updates in development first - - Test skill updates in development environment before deploying to production, especially for major version updates. - - +Test skill updates in development environment before deploying to production, especially for major version updates. ## See Also diff --git a/webdocs/configuration/init-command.mdx b/webdocs/configuration/init-command.mdx index f52b1edc..ca1a1cd2 100644 --- a/webdocs/configuration/init-command.mdx +++ b/webdocs/configuration/init-command.mdx @@ -7,17 +7,17 @@ description: "Create skill-project.toml for skill authors and project configurat The `fastskill init` command creates a `skill-project.toml` file for skill authors. This command extracts metadata from an existing `SKILL.md` file (if present) and interactively prompts for any missing information to create a properly configured skill project. - + This command is for **skill authors** who want to create a new skill project. It generates the `skill-project.toml` manifest file that defines your skill's metadata, dependencies, and configuration. For general FastSkill setup, see the [Installation Guide](/installation). - + - + **Context Detection**: `fastskill init` automatically detects whether you're working in a skill directory or project root: - **Skill-level**: If run in a directory containing `SKILL.md`, creates `skill-project.toml` with `[metadata]` section (for skill authors) - **Project-level**: If run at project root, can create `skill-project.toml` with `[dependencies]` section (for skill consumers) See [Skill Commands](/cli-reference/skill-commands) for details on skill-level initialization. - + ## What It Does diff --git a/webdocs/configuration/meta.json b/webdocs/configuration/meta.json new file mode 100644 index 00000000..368fd134 --- /dev/null +++ b/webdocs/configuration/meta.json @@ -0,0 +1,5 @@ +{ + "pages": [ + "init-command" + ] +} diff --git a/webdocs/evals-quality/meta.json b/webdocs/evals-quality/meta.json new file mode 100644 index 00000000..995b7b49 --- /dev/null +++ b/webdocs/evals-quality/meta.json @@ -0,0 +1,8 @@ +{ + "pages": [ + "overview", + "setup", + "run-evals", + "cluster-analysis" + ] +} diff --git a/webdocs/examples/advanced-patterns.mdx b/webdocs/examples/advanced-patterns.mdx index 8a412fd1..ed5bc985 100644 --- a/webdocs/examples/advanced-patterns.mdx +++ b/webdocs/examples/advanced-patterns.mdx @@ -15,6 +15,6 @@ Advanced patterns demonstrate sophisticated ways to use FastSkill in complex sce - Enterprise integration - Advanced routing strategies - + Advanced patterns showcase FastSkill's capabilities in complex, real-world scenarios. - + diff --git a/webdocs/examples/integration-tutorials.mdx b/webdocs/examples/integration-tutorials.mdx index ca96edef..2be8fd9a 100644 --- a/webdocs/examples/integration-tutorials.mdx +++ b/webdocs/examples/integration-tutorials.mdx @@ -19,6 +19,6 @@ Integration tutorials show how to connect FastSkill with various AI agent framew Follow the step-by-step tutorials to integrate FastSkill into your projects. - + Integration tutorials provide practical examples for common use cases and frameworks. - + diff --git a/webdocs/examples/meta.json b/webdocs/examples/meta.json new file mode 100644 index 00000000..eed8e166 --- /dev/null +++ b/webdocs/examples/meta.json @@ -0,0 +1,6 @@ +{ + "pages": [ + "advanced-patterns", + "integration-tutorials" + ] +} diff --git a/webdocs/index.mdx b/webdocs/index.mdx index 8d7d897a..d83e48a3 100644 --- a/webdocs/index.mdx +++ b/webdocs/index.mdx @@ -3,13 +3,11 @@ title: "FastSkill" description: "Package manager and operational toolkit for Agent AI Skills. Discovery, installation, versioning, validation, evals, and deployment at scale." --- - + New here? Read the [Welcome](/welcome) page for the full story, then [Quick start](/quickstart) and [Installation](/installation). - + - FastSkill overview - ## What is FastSkill? @@ -19,31 +17,31 @@ The project is designed around a **CLI-first workflow**; local **`fastskill serv ## What you can do - - + + `add`, `install`, `update`, `remove`, `list`, `read` with `skill-project.toml` and `skills.lock`. - + Structure checks on install and reconciliation across manifest, lock, and disk. See [Skill validation](/skill-management/validation). - + `fastskill eval validate | run | report | score` for defined quality suites. See [eval command](/cli-reference/eval-command). - + Catalog search by default; `--local` for installed skills, embeddings, and keyword fallback. - + `fastskill doctor` reports configuration and environment readiness, including whether semantic search is available. See [tooling commands](/cli-reference/tooling-commands). - + `repos` for remote sources and registry browsing. See [Registry overview](/registry/overview). - + ## Quick start (CLI) @@ -72,20 +70,21 @@ Then optional: `fastskill reindex`, `fastskill search "…" --local`, `fastskill ## Next steps - - - [Installation](/installation) for the `fastskill` binary. - - - [Welcome](/welcome) and [Manifest system](/skill-management/manifest-system). - - - [Skill validation](/skill-management/validation), [Evals and quality](/evals-quality/overview), [CLI reference](/cli-reference/overview). - - - [Cursor integration](/integration/cursor-integration) or [Claude Code integration](/integration/claude-code-integration). - - +### 1. Install + +[Installation](/installation) for the `fastskill` binary. + +### 2. Learn the model + +[Welcome](/welcome) and [Manifest system](/skill-management/manifest-system). + +### 3. Operate skills + +[Skill validation](/skill-management/validation), [Evals and quality](/evals-quality/overview), [CLI reference](/cli-reference/overview). + +### 4. Integrate + +[Cursor integration](/integration/cursor-integration) or [Claude Code integration](/integration/claude-code-integration). ## Getting help diff --git a/webdocs/installation.mdx b/webdocs/installation.mdx index dcc8f6ea..8bcc5611 100644 --- a/webdocs/installation.mdx +++ b/webdocs/installation.mdx @@ -18,8 +18,8 @@ Before installing FastSkill, ensure your system meets these requirements: Pick one method. **Homebrew** (macOS and Linux) and **Scoop** (Windows) stay updated with releases; use **GitHub Releases** or the **install script** if you prefer a standalone binary. - - + + [Homebrew](https://brew.sh/) installs a pre-built `fastskill` on both **Apple Silicon** and **Intel** Macs, and on Linux where the tap ships bottles. @@ -30,12 +30,12 @@ fastskill -V Details and formula updates live in the [gofastskill/homebrew-cli](https://github.com/gofastskill/homebrew-cli) tap repository. - + If `brew install` fails with a tap error, run `brew update` and try again, or use the **GitHub Releases** or **install script** tab. - + - + [Scoop](https://scoop.sh/) installs `fastskill.exe` and keeps it on your PATH. @@ -49,7 +49,7 @@ See [gofastskill/scoop-bucket](https://github.com/gofastskill/scoop-bucket) for - + One-liner from the repository (detects OS, downloads a release binary, installs to `/usr/local/bin` or `~/.local/bin` if `sudo` is not available): @@ -61,12 +61,12 @@ Options (run `./install.sh --help` after downloading the script): `--user`, `--p - + Download a pre-built binary from [GitHub Releases](https://github.com/gofastskill/fastskill/releases). Replace `VERSION` with the tag you want (for example `0.9.16`; assets use `v${VERSION}` in the URL). - - +### 1. macOS (Apple Silicon) + ```bash VERSION="0.9.16" curl -fL "https://github.com/gofastskill/fastskill/releases/download/v${VERSION}/fastskill-aarch64-apple-darwin.tar.gz" -o fastskill.tgz @@ -75,9 +75,9 @@ sudo mv fastskill /usr/local/bin/ fastskill -V ``` Asset name: `fastskill-aarch64-apple-darwin.tar.gz`. - - +### 2. macOS (Intel) + ```bash VERSION="0.9.16" curl -fL "https://github.com/gofastskill/fastskill/releases/download/v${VERSION}/fastskill-x86_64-apple-darwin.tar.gz" -o fastskill.tgz @@ -86,9 +86,9 @@ sudo mv fastskill /usr/local/bin/ fastskill -V ``` Asset name: `fastskill-x86_64-apple-darwin.tar.gz`. - - +### 3. Linux (x86_64, glibc, with git support) + ```bash VERSION="0.9.16" curl -fL "https://github.com/gofastskill/fastskill/releases/download/v${VERSION}/fastskill-x86_64-unknown-linux-gnu.tar.gz" -o fastskill.tgz @@ -97,20 +97,18 @@ sudo mv fastskill /usr/local/bin/ fastskill -V ``` Requires a recent glibc (see release notes). For maximum portability (static binary, no bundled `git2`), use **`fastskill-x86_64-unknown-linux-musl.tar.gz`** instead and rely on system `git` for Git URLs. - - +### 4. Windows (zip) + Download `fastskill-x86_64-pc-windows-msvc.zip` from the release page, extract it, add the folder to **PATH**, then run: ```powershell fastskill.exe -V ``` - - - + Prefer a user-local path on macOS or Linux? Move `fastskill` to `~/.local/bin/` and ensure that directory is on your `PATH` instead of using `sudo`. - + @@ -183,52 +181,52 @@ If you already have a project with `skill-project.toml`, try `fastskill list` or ## Troubleshooting - - - + + + **Homebrew**: If the tap is missing, install with `brew install gofastskill/cli/fastskill`. See [homebrew-cli](https://github.com/gofastskill/homebrew-cli) for issues. - + - + **Scoop**: Ensure the bucket was added (`scoop bucket list` should show `gofastskill`). See [scoop-bucket](https://github.com/gofastskill/scoop-bucket) if `scoop install fastskill` fails. - + - + **Binary not found in PATH**: After extracting a release archive, move `fastskill` (or add the folder containing `fastskill.exe`) to a directory on your PATH (`/usr/local/bin`, `~/.local/bin`, or Windows user PATH). - + - + **Permission denied (Linux)**: If you get permission errors, use `sudo` when moving to `/usr/local/bin/`, or install to `~/.local/bin/` instead and ensure it's in your PATH. - + - + **Windows security warning**: Windows may show a security warning for unsigned binaries. Click "More info" and then "Run anyway" if you trust the source. - + - - + + **Embedding configuration required**: Create `.fastskill/config.yaml` with OpenAI API configuration. - + - + **OpenAI API key not found**: Set `OPENAI_API_KEY` environment variable or configure in `.fastskill/config.yaml`. - + - - + + **macOS security**: If you get security warnings, go to System Settings > Privacy & Security and allow the binary. - + - + **Windows antivirus**: If Windows blocks the downloaded binary, add an exception for the folder where you keep `fastskill.exe`. - + - + - + Still having issues? Check the [troubleshooting section](/troubleshooting). - + diff --git a/webdocs/integration/cursor-integration.mdx b/webdocs/integration/cursor-integration.mdx index 1e296266..17f087eb 100644 --- a/webdocs/integration/cursor-integration.mdx +++ b/webdocs/integration/cursor-integration.mdx @@ -9,11 +9,11 @@ Cursor discovers skills **directly** from the skills directory (`.claude/skills/ 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. - + 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. - + ## Quick start diff --git a/webdocs/integration/meta.json b/webdocs/integration/meta.json new file mode 100644 index 00000000..ab1f9ccc --- /dev/null +++ b/webdocs/integration/meta.json @@ -0,0 +1,6 @@ +{ + "pages": [ + "cursor-integration", + "claude-code-integration" + ] +} diff --git a/webdocs/meta.json b/webdocs/meta.json new file mode 100644 index 00000000..4b9943d8 --- /dev/null +++ b/webdocs/meta.json @@ -0,0 +1,33 @@ +{ + "pages": [ + "---Getting Started---", + "welcome", + "index", + "quickstart", + "installation", + "cheatsheet", + "---Configuration---", + "configuration", + "---Skill Management---", + "skill-management", + "---Evals & Quality---", + "evals-quality", + "---Skill Optimization---", + "optimize", + "---CLI Reference---", + "cli-reference", + "---Registry---", + "registry", + "---Advanced Topics---", + "security", + "---Integration---", + "integration", + "---Testing & Examples---", + "testing", + "tool-calling", + "progressive-loading", + "examples", + "---Troubleshooting---", + "troubleshooting" + ] +} diff --git a/webdocs/mint.json b/webdocs/mint.json deleted file mode 100644 index f0fcd99b..00000000 --- a/webdocs/mint.json +++ /dev/null @@ -1,129 +0,0 @@ -{ - "name": "FastSkill", - "logo": { - "dark": "/logo/dark.svg", - "light": "/logo/light.svg" - }, - "favicon": "/favicon.svg", - "colors": { - "primary": "#0D9373", - "light": "#10B981", - "dark": "#059669" - }, - "topbarLinks": [ - { - "name": "GitHub", - "url": "https://github.com/gofastskill/fastskill" - } - ], - "topbarCtaButton": { - "name": "Get Started", - "url": "/welcome" - }, - "anchors": [ - { - "name": "GitHub", - "icon": "github", - "url": "https://github.com/gofastskill/fastskill" - } - ], - "navigation": [ - { - "group": "Getting Started", - "pages": [ - "welcome", - "index", - "quickstart", - "installation", - "cheatsheet" - ] - }, - { - "group": "Configuration", - "pages": [ - "configuration/init-command" - ] - }, - { - "group": "Skill Management", - "pages": [ - "skill-management/manifest-system", - "skill-management/validation", - "skill-management/reconciliation" - ] - }, - { - "group": "Evals & Quality", - "pages": [ - "evals-quality/overview", - "evals-quality/setup", - "evals-quality/run-evals", - "evals-quality/cluster-analysis" - ] - }, - { - "group": "Skill Optimization", - "pages": [ - "optimize/overview", - "optimize/setup", - "optimize/configuration", - "optimize/running", - "optimize/results" - ] - }, - { - "group": "CLI Reference", - "pages": [ - "cli-reference/overview", - "cli-reference/skill-commands", - "cli-reference/discovery-commands", - "cli-reference/init-command", - "cli-reference/install-command", - "cli-reference/update-command", - "cli-reference/reindex-command", - "cli-reference/search-command", - "cli-reference/serve-command", - "cli-reference/repository-command", - "cli-reference/eval-command", - "cli-reference/tooling-commands" - ] - }, - { - "group": "Registry", - "pages": [ - "registry/overview", - "registry/repository-architecture", - "registry/index-system", - "registry/sources", - "registry/marketplace-json", - "registry/web-ui" - ] - }, - { - "group": "Advanced Topics", - "pages": [ - "security/model", - "security/best-practices" - ] - }, - { - "group": "Integration", - "pages": [ - "integration/cursor-integration", - "integration/claude-code-integration" - ] - } - ], - "footerSocials": { - "github": "https://github.com/gofastskill/fastskill", - "twitter": "https://twitter.com/fastskill" - }, - "analytics": { - "ga4": { - "measurementId": "G-XXXXXXXXXX" - } - }, - "search": { - "indexName": "fastskill" - } -} \ No newline at end of file diff --git a/webdocs/optimize/meta.json b/webdocs/optimize/meta.json new file mode 100644 index 00000000..c4cca546 --- /dev/null +++ b/webdocs/optimize/meta.json @@ -0,0 +1,9 @@ +{ + "pages": [ + "overview", + "setup", + "configuration", + "running", + "results" + ] +} diff --git a/webdocs/progressive-loading/meta.json b/webdocs/progressive-loading/meta.json new file mode 100644 index 00000000..e851eee7 --- /dev/null +++ b/webdocs/progressive-loading/meta.json @@ -0,0 +1,6 @@ +{ + "pages": [ + "strategies", + "performance" + ] +} diff --git a/webdocs/progressive-loading/performance.mdx b/webdocs/progressive-loading/performance.mdx index 6af0234c..9bc1bcae 100644 --- a/webdocs/progressive-loading/performance.mdx +++ b/webdocs/progressive-loading/performance.mdx @@ -18,6 +18,6 @@ Performance optimization ensures FastSkill runs efficiently in your environment. Track performance metrics and identify optimization opportunities. - + Regular performance monitoring helps maintain optimal FastSkill operation. - + diff --git a/webdocs/progressive-loading/strategies.mdx b/webdocs/progressive-loading/strategies.mdx index 06ecf21c..9676fafb 100644 --- a/webdocs/progressive-loading/strategies.mdx +++ b/webdocs/progressive-loading/strategies.mdx @@ -25,6 +25,6 @@ Intelligent caching with configurable eviction policies for optimal performance. FastSkill automatically manages loading strategies based on configuration and usage patterns. - + Choose loading strategies based on your performance requirements and usage patterns. - + diff --git a/webdocs/quickstart.mdx b/webdocs/quickstart.mdx index 63c077a5..161f9457 100644 --- a/webdocs/quickstart.mdx +++ b/webdocs/quickstart.mdx @@ -10,24 +10,24 @@ description: "First skills with FastSkill in minutes: install, manifest, add, in ## Five-minute setup (CLI) - - +### 1. Install the CLI + Follow [Installation](/installation), then confirm: ```bash fastskill -V ``` - - +### 2. Create a manifest + Create `skill-project.toml` at your project root: ```toml skill-project.toml [dependencies] demo-skill = { source = "local", path = "./skills/demo-skill", editable = true, groups = ["dev"] } ``` - - +### 3. Add a skill + Pick the source that matches your workflow: ```bash # From a public registry ID @@ -39,26 +39,26 @@ fastskill add ./skills/demo-skill -e --group dev # From git with a branch fastskill add https://github.com/org/skill.git --branch main ``` - - +### 4. Install & index + ```bash fastskill install fastskill reindex ``` - - +### 5. Search & verify + ```bash fastskill search "text processing" --local --format json ``` - + You should see JSON results for installed skills. If empty, run `fastskill install`, then `fastskill reindex`, and search again. - - + + +### 6. Optional: serve UI - ```bash fastskill serve --port 8080 ``` @@ -68,8 +68,6 @@ The HTTP API is available under `/api/v1/…`, e.g.: - `GET http://localhost:8080/api/v1/skills` — list installed skills - `GET http://localhost:8080/healthz` — liveness probe - `GET http://localhost:8080/readyz` — readiness probe - - ## Use-case quick recipes diff --git a/webdocs/registry/meta.json b/webdocs/registry/meta.json new file mode 100644 index 00000000..19a7ba2f --- /dev/null +++ b/webdocs/registry/meta.json @@ -0,0 +1,10 @@ +{ + "pages": [ + "overview", + "repository-architecture", + "index-system", + "sources", + "marketplace-json", + "web-ui" + ] +} diff --git a/webdocs/registry/repository-architecture.mdx b/webdocs/registry/repository-architecture.mdx index b4bc6d85..19d659a7 100644 --- a/webdocs/registry/repository-architecture.mdx +++ b/webdocs/registry/repository-architecture.mdx @@ -7,9 +7,9 @@ description: "Understanding FastSkill's multi-source repository system for skill FastSkill implements a flexible, multi-source repository system that allows you to discover and install skills from various sources including Git repositories, HTTP registries, ZIP files, and local filesystem paths. - + Repository configuration is stored in `[tool.fastskill.repositories]` section of `skill-project.toml` or in `.claude/repositories.toml` for backward compatibility. - + ## Repository Types @@ -233,9 +233,9 @@ auth_type = "basic" auth_value = "username:password" ``` - + Basic auth stores credentials in plain text. Use only for test environments or secure configuration management. - + **Use cases:** - Simple HTTP registries @@ -547,81 +547,79 @@ Use environment-specific repositories or branch parameters to control which skil ## Troubleshooting - - - + + + **Repository priority**: Verify skill ID is spelled correctly and exists in at least one repository. - + - + **Resolution**: Use `fastskill repos list` to see all repositories and `fastskill repos test ` to verify connectivity. - + - + **Check marketplace.json**: For git-marketplace repositories, verify marketplace.json contains the skill ID. - + - - + + **Invalid credentials**: Check auth_type and auth_value are correct. - + - + **Token expired**: PATs and API keys may expire. Generate new credentials and update configuration. - + - + **Resolution**: Test authentication with `fastskill repos test `. - + - - + + **Wrong priority**: Lower numbers have higher priority. Check your priority values. - + - + **Resolution**: Use `fastskill repos info ` to verify repository priority. - + - + ## Best Practices - - - Prefer `skill-project.toml` [tool.fastskill.repositories] section over `.claude/repositories.toml` for better project organization. - +### 1. Use skill-project.toml for repository configuration - - Use priority to control repository search order. Lower numbers are checked first (0, 1, 2, ...). - +Prefer `skill-project.toml` [tool.fastskill.repositories] section over `.claude/repositories.toml` for better project organization. - - Secure private repositories with PAT, SSH keys, or API keys. Never commit credentials to version control. - +### 2. Set appropriate priorities - - Use `fastskill repos test ` to verify repository connectivity and authentication before relying on it. - +Use priority to control repository search order. Lower numbers are checked first (0, 1, 2, ...). - - Only configure repositories you actively use. Remove or comment out unused repositories to speed up resolution. - +### 3. Use authentication for private repositories - - For team skill sharing, use git-marketplace type with marketplace.json for comprehensive skill metadata and search. - +Secure private repositories with PAT, SSH keys, or API keys. Never commit credentials to version control. - - Commit repository configuration to version control along with skill dependencies for reproducible setups. - +### 4. Test repositories before use - - Use `fastskill repos refresh` to update repository caches after remote changes. - - +Use `fastskill repos test ` to verify repository connectivity and authentication before relying on it. + +### 5. Keep repositories minimal + +Only configure repositories you actively use. Remove or comment out unused repositories to speed up resolution. + +### 6. Use git-marketplace for team skills + +For team skill sharing, use git-marketplace type with marketplace.json for comprehensive skill metadata and search. + +### 7. Version control repository configuration + +Commit repository configuration to version control along with skill dependencies for reproducible setups. + +### 8. Refresh repositories after changes + +Use `fastskill repos refresh` to update repository caches after remote changes. ## See Also diff --git a/webdocs/security/best-practices.mdx b/webdocs/security/best-practices.mdx index c30a96ce..03e8105b 100644 --- a/webdocs/security/best-practices.mdx +++ b/webdocs/security/best-practices.mdx @@ -21,6 +21,6 @@ Security best practices ensure FastSkill operates safely in production environme - Monitor security events - Regular security updates - + Security is an ongoing process. Regular reviews and updates are essential for maintaining a secure FastSkill deployment. - + diff --git a/webdocs/security/meta.json b/webdocs/security/meta.json new file mode 100644 index 00000000..cc9c8cc4 --- /dev/null +++ b/webdocs/security/meta.json @@ -0,0 +1,6 @@ +{ + "pages": [ + "model", + "best-practices" + ] +} diff --git a/webdocs/security/model.mdx b/webdocs/security/model.mdx index 1498d6d0..716c0adf 100644 --- a/webdocs/security/model.mdx +++ b/webdocs/security/model.mdx @@ -22,6 +22,6 @@ FastSkill implements multiple layers of security to protect against malicious sk - Monitor execution logs - Keep dependencies updated - + Security is built into FastSkill's core architecture to protect your systems and data. - + diff --git a/webdocs/skill-management/meta.json b/webdocs/skill-management/meta.json new file mode 100644 index 00000000..d137fec3 --- /dev/null +++ b/webdocs/skill-management/meta.json @@ -0,0 +1,7 @@ +{ + "pages": [ + "manifest-system", + "validation", + "reconciliation" + ] +} diff --git a/webdocs/skill-management/reconciliation.mdx b/webdocs/skill-management/reconciliation.mdx index d3f6f327..07d57243 100644 --- a/webdocs/skill-management/reconciliation.mdx +++ b/webdocs/skill-management/reconciliation.mdx @@ -96,9 +96,9 @@ web-scraper 1.2.3 git ok data-processor 2.2.0 registry mismatch (lock: 2.1.0) ``` - + Version mismatches indicate manual changes or corruption. Resolve to ensure reproducibility. - + **Resolution:** ```bash @@ -298,33 +298,31 @@ fastskill list # dev-tool: missing (expected, excluded by --without dev) ``` - + Missing status is expected for skills excluded by group filters. Only report as issues if all skills should be installed. - + ## Best Practices - - - Always commit `skill-project.toml` and `skills.lock` together to version control. This ensures team members can reproduce exact installations. - +### 1. Commit both manifest and lockfile - - Run `fastskill list` after installing, updating, or removing skills to verify reconciliation status. - +Always commit `skill-project.toml` and `skills.lock` together to version control. This ensures team members can reproduce exact installations. - - Always use `fastskill install --lock` for production deployments to ensure exact version reproducibility. - +### 2. Run fastskill list after changes - - Version mismatches indicate manual changes or corruption. Investigate and resolve promptly to maintain consistency. - +Run `fastskill list` after installing, updating, or removing skills to verify reconciliation status. - - Remove or add extraneous skills to `skill-project.toml` to avoid confusion and ensure clean skill ecosystem. - - +### 3. Use --lock for production + +Always use `fastskill install --lock` for production deployments to ensure exact version reproducibility. + +### 4. Investigate mismatches promptly + +Version mismatches indicate manual changes or corruption. Investigate and resolve promptly to maintain consistency. + +### 5. Remove extraneous skills + +Remove or add extraneous skills to `skill-project.toml` to avoid confusion and ensure clean skill ecosystem. ## Common Reconciliation Issues @@ -450,49 +448,49 @@ exit 0 ## Troubleshooting - - - + + + **Skills directory incorrect**: Check that `skills_directory` in `.fastskill/config.yaml` points to correct location. - + - + **skill-project.toml missing**: Create `skill-project.toml` or use `fastskill init`. - + - + **Resolution**: Run `fastskill install` to install skills from manifest. - + - - + + **Manual installations**: Skills may have been added outside FastSkill management. - + - + **Resolution**: Add to `skill-project.toml` if intentional, or remove with `fastskill remove`. - + - + **Prevention**: Always use `fastskill add` to install skills for proper tracking. - + - - + + **Manual file changes**: Skills may have been updated manually (e.g., git pull). - + - + **Corrupted lockfile**: Lockfile may be out of sync with actual state. - + - + **Resolution**: Run `fastskill install --lock` to reinstall from lockfile, or `fastskill update` to update lockfile. - + - + ## See Also diff --git a/webdocs/skill-management/validation.mdx b/webdocs/skill-management/validation.mdx index 2f13ea9e..a4909882 100644 --- a/webdocs/skill-management/validation.mdx +++ b/webdocs/skill-management/validation.mdx @@ -7,9 +7,9 @@ description: "Comprehensive guide to validating FastSkill skill definitions incl Skill validation means checking that each skill installs cleanly, exposes the metadata agents expect, and matches what your `skill-project.toml` declares. - + Validation happens at multiple stages: definition validation, registration validation, and runtime validation. - + ## What FastSkill checks @@ -25,62 +25,71 @@ Run `fastskill install` or `fastskill add …` to surface validation errors befo ### Required Fields - +#### `id` (string, required) + - Must be unique within the service - Alphanumeric characters, dashes, and underscores only - 3-50 characters in length - Cannot start or end with dashes/underscores - - + +#### `name` (string, required) + - Human-readable name - 1-100 characters in length - No special formatting requirements - - + +#### `description` (string, required) + - Detailed description of functionality - 10-500 characters in length - Should explain what the skill does - - + +#### `version` (string, required) + - Semantic version format (e.g., "1.0.0") - Follows MAJOR.MINOR.PATCH convention - Should be updated for breaking changes - + ### Optional Fields Validation - +#### `tags` (string, optional) + - Comma-separated list of tags - Each tag 2-30 characters - Alphanumeric, dashes, and underscores only - Maximum 20 tags - - + +#### `capabilities` (string, optional) + - Comma-separated list of capabilities - Each capability 3-50 characters - Descriptive of actual functionality - Maximum 20 capabilities - - + +#### `skill_file` (string, optional) + - Path relative to skill storage directory - Must exist and be readable - Should be a Python file or markdown document - - + +#### `execution_timeout` (integer, optional) + - 1-300 seconds - Must be reasonable for the skill's operations - - + +#### `memory_limit_mb` (integer, optional) + - 32-2048 MB - Must be sufficient for skill execution - + ## Automatic Validation @@ -128,62 +137,59 @@ If you use automation, run the same commands after `fastskill install` or `fasts ## Best Practices - - - Run `fastskill install` and `fastskill list` whenever `skill-project.toml` or skills change. - +### 1. Validate after every manifest change + +Run `fastskill install` and `fastskill list` whenever `skill-project.toml` or skills change. - - Combine structure, security, and quality validation for comprehensive coverage. - +### 2. Use multiple validation levels - - Integrate validation into your CI/CD pipeline to catch issues before they reach production. - +Combine structure, security, and quality validation for comprehensive coverage. - - Track validation success rates and common issues to improve skill quality over time. - +### 3. Set up automated validation - - Capture which registries, groups, and approval steps apply to your org so skill owners know what "valid" means for you. - - +Integrate validation into your CI/CD pipeline to catch issues before they reach production. + +### 4. Monitor validation metrics + +Track validation success rates and common issues to improve skill quality over time. + +### 5. Write expectations in your team handbook + +Capture which registries, groups, and approval steps apply to your org so skill owners know what "valid" means for you. ## Troubleshooting - - - + + + **Missing required fields**: Ensure all required fields are present and have valid values. - + Required fields: - `id`: Must be alphanumeric with dashes/underscores only - `name`: Human-readable name - `description`: Detailed description - `version`: Semantic version (e.g., "1.0.0") - + - + **Invalid field types**: Check that field values match expected types. - + - `id`, `name`, `description`, `version`: strings - `enabled`: boolean - `timeout`: optional integer - + - - - **Common validation issues**: + + + **Common validation issues**: - Invalid skill ID format (must be alphanumeric, dashes, underscores only) - Skill ID too long (max 255 characters) - Invalid file paths - + - - + - + Effective validation catches issues early and ensures skills meet quality standards. Invest time in setting up comprehensive validation for your skill ecosystem. - + diff --git a/webdocs/testing/debugging.mdx b/webdocs/testing/debugging.mdx index 66e7c3b3..6abacce9 100644 --- a/webdocs/testing/debugging.mdx +++ b/webdocs/testing/debugging.mdx @@ -21,6 +21,6 @@ Debugging tools help identify and resolve FastSkill issues quickly. - Execution errors - Network connectivity - + Effective debugging tools help maintain FastSkill's reliability and performance. - + diff --git a/webdocs/testing/meta.json b/webdocs/testing/meta.json new file mode 100644 index 00000000..706f444b --- /dev/null +++ b/webdocs/testing/meta.json @@ -0,0 +1,6 @@ +{ + "pages": [ + "framework", + "debugging" + ] +} diff --git a/webdocs/tool-calling/development.mdx b/webdocs/tool-calling/development.mdx index f1f13526..827be84b 100644 --- a/webdocs/tool-calling/development.mdx +++ b/webdocs/tool-calling/development.mdx @@ -22,6 +22,6 @@ Tool development enables you to extend FastSkill with custom functionality. - Add comprehensive documentation - Test thoroughly before deployment - + Custom tools extend FastSkill's capabilities and integrate with the skill ecosystem. - + diff --git a/webdocs/tool-calling/meta.json b/webdocs/tool-calling/meta.json new file mode 100644 index 00000000..e6ebd59f --- /dev/null +++ b/webdocs/tool-calling/meta.json @@ -0,0 +1,5 @@ +{ + "pages": [ + "development" + ] +} diff --git a/webdocs/TROUBLESHOOTING.md b/webdocs/troubleshooting.mdx similarity index 99% rename from webdocs/TROUBLESHOOTING.md rename to webdocs/troubleshooting.mdx index f03f828a..e9b265da 100644 --- a/webdocs/TROUBLESHOOTING.md +++ b/webdocs/troubleshooting.mdx @@ -34,7 +34,7 @@ If CDN access is permanently blocked, you can use local SVG icons instead: 1. Replace icon names with file paths: ```markdown - + ``` 2. Store SVG icons in `/icons/` directory: