foliko 1.1.13 → 1.1.14

package/skills/find-skills/AGENTS.md

@@ -1,162 +1,162 @@
-# AGENTS.md
-
-This file provides guidance to AI coding agents working on the `skills` CLI codebase.
-
-## Project Overview
-
-`skills` is the CLI for the open agent skills ecosystem.
-
-## Commands
-
-| Command                       | Description                                         |
-| ----------------------------- | --------------------------------------------------- |
-| `skills`                      | Show banner with available commands                 |
-| `skills add <pkg>`            | Install skills from git repos, URLs, or local paths |
-| `skills experimental_install` | Restore skills from skills-lock.json                |
-| `skills experimental_sync`    | Sync skills from node_modules into agent dirs       |
-| `skills list`                 | List installed skills (alias: `ls`)                 |
-| `skills check`                | Check for available skill updates                   |
-| `skills update`               | Update all skills to latest versions                |
-| `skills init [name]`          | Create a new SKILL.md template                      |
-
-Aliases: `skills a` works for `add`. `skills i`, `skills install` (no args) restore from `skills-lock.json`. `skills ls` works for `list`. `skills experimental_install` restores from `skills-lock.json`. `skills experimental_sync` crawls `node_modules` for skills.
-
-## Architecture
-
-```
-src/
-├── cli.ts           # Main entry point, command routing, init/check/update
-├── cli.test.ts      # CLI tests
-├── add.ts           # Core add command logic
-├── add.test.ts      # Add command tests
-├── list.ts          # List installed skills command
-├── list.test.ts     # List command tests
-├── agents.ts        # Agent definitions and detection
-├── installer.ts     # Skill installation logic (symlink/copy) + listInstalledSkills
-├── skills.ts        # Skill discovery and parsing
-├── skill-lock.ts    # Global lock file management (~/.agents/.skill-lock.json)
-├── local-lock.ts    # Local lock file management (skills-lock.json, checked in)
-├── sync.ts          # Sync command - crawl node_modules for skills
-├── source-parser.ts # Parse git URLs, GitHub shorthand, local paths
-├── git.ts           # Git clone operations
-├── telemetry.ts     # Anonymous usage tracking
-├── types.ts         # TypeScript types
-├── mintlify.ts      # Mintlify skill fetching (legacy)
-├── providers/       # Remote skill providers (GitHub, HuggingFace, Mintlify)
-│   ├── index.ts
-│   ├── registry.ts
-│   ├── types.ts
-│   ├── huggingface.ts
-│   └── mintlify.ts
-├── init.test.ts     # Init command tests
-└── test-utils.ts    # Test utilities
-
-tests/
-├── sanitize-name.test.ts     # Tests for sanitizeName (path traversal prevention)
-├── skill-matching.test.ts    # Tests for filterSkills (multi-word skill name matching)
-├── source-parser.test.ts     # Tests for URL/path parsing
-├── installer-symlink.test.ts # Tests for symlink installation
-├── list-installed.test.ts    # Tests for listing installed skills
-├── skill-path.test.ts        # Tests for skill path handling
-├── wellknown-provider.test.ts # Tests for well-known provider
-└── dist.test.ts              # Tests for built distribution
-```
-
-## Update Checking System
-
-### How `skills check` and `skills update` Work
-
-1. Read `~/.agents/.skill-lock.json` for installed skills
-2. For each skill, get `skillFolderHash` from lock file
-3. POST to `https://add-skill.vercel.sh/check-updates` with:
-   ```json
-   {
-     "skills": [{ "name": "...", "source": "...", "skillFolderHash": "..." }],
-     "forceRefresh": true
-   }
-   ```
-4. API fetches fresh content from GitHub, computes hash, compares
-5. Returns list of skills with different hashes (updates available)
-
-### Why `forceRefresh: true`?
-
-Both `check` and `update` always send `forceRefresh: true`. This ensures the API fetches fresh content from GitHub rather than using its Redis cache.
-
-**Without forceRefresh:** Users saw phantom "updates available" due to stale cached hashes. The fix was to always fetch fresh.
-
-**Tradeoff:** Slightly slower (GitHub API call per skill), but always accurate.
-
-### Lock File Compatibility
-
-The lock file format is v3. Key field: `skillFolderHash` (GitHub tree SHA for the skill folder).
-
-If reading an older lock file version, it's wiped. Users must reinstall skills to populate the new format.
-
-## Key Integration Points
-
-| Feature                    | Implementation                              |
-| -------------------------- | ------------------------------------------- |
-| `skills add`               | `src/add.ts` - full implementation          |
-| `skills experimental_sync` | `src/sync.ts` - crawl node_modules          |
-| `skills check`             | `POST /check-updates` API                   |
-| `skills update`            | `POST /check-updates` + reinstall per skill |
-
-## Development
-
-```bash
-# Install dependencies
-pnpm install
-
-# Build
-pnpm build
-
-# Test locally
-pnpm dev add vercel-labs/agent-skills --list
-pnpm dev experimental_sync
-pnpm dev check
-pnpm dev update
-pnpm dev init my-skill
-
-# Run all tests
-pnpm test
-
-# Run specific test file(s)
-pnpm test tests/sanitize-name.test.ts
-pnpm test tests/skill-matching.test.ts tests/source-parser.test.ts
-
-# Type check
-pnpm type-check
-
-# Format code
-pnpm format
-```
-
-## Code Style
-
-This project uses Prettier for code formatting. **Always run `pnpm format` before committing changes** to ensure consistent formatting.
-
-```bash
-# Format all files
-pnpm format
-
-# Check formatting without fixing
-pnpm prettier --check .
-```
-
-CI will fail if code is not properly formatted.
-
-## Publishing
-
-```bash
-# 1. Bump version in package.json
-# 2. Build
-pnpm build
-# 3. Publish
-npm publish
-```
-
-## Adding a New Agent
-
-1. Add the agent definition to `src/agents.ts`
-2. Run `pnpm run -C scripts validate-agents.ts` to validate
-3. Run `pnpm run -C scripts sync-agents.ts` to update README.md
+# AGENTS.md
+
+This file provides guidance to AI coding agents working on the `skills` CLI codebase.
+
+## Project Overview
+
+`skills` is the CLI for the open agent skills ecosystem.
+
+## Commands
+
+| Command                       | Description                                         |
+| ----------------------------- | --------------------------------------------------- |
+| `skills`                      | Show banner with available commands                 |
+| `skills add <pkg>`            | Install skills from git repos, URLs, or local paths |
+| `skills experimental_install` | Restore skills from skills-lock.json                |
+| `skills experimental_sync`    | Sync skills from node_modules into agent dirs       |
+| `skills list`                 | List installed skills (alias: `ls`)                 |
+| `skills check`                | Check for available skill updates                   |
+| `skills update`               | Update all skills to latest versions                |
+| `skills init [name]`          | Create a new SKILL.md template                      |
+
+Aliases: `skills a` works for `add`. `skills i`, `skills install` (no args) restore from `skills-lock.json`. `skills ls` works for `list`. `skills experimental_install` restores from `skills-lock.json`. `skills experimental_sync` crawls `node_modules` for skills.
+
+## Architecture
+
+```
+src/
+├── cli.ts           # Main entry point, command routing, init/check/update
+├── cli.test.ts      # CLI tests
+├── add.ts           # Core add command logic
+├── add.test.ts      # Add command tests
+├── list.ts          # List installed skills command
+├── list.test.ts     # List command tests
+├── agents.ts        # Agent definitions and detection
+├── installer.ts     # Skill installation logic (symlink/copy) + listInstalledSkills
+├── skills.ts        # Skill discovery and parsing
+├── skill-lock.ts    # Global lock file management (~/.agents/.skill-lock.json)
+├── local-lock.ts    # Local lock file management (skills-lock.json, checked in)
+├── sync.ts          # Sync command - crawl node_modules for skills
+├── source-parser.ts # Parse git URLs, GitHub shorthand, local paths
+├── git.ts           # Git clone operations
+├── telemetry.ts     # Anonymous usage tracking
+├── types.ts         # TypeScript types
+├── mintlify.ts      # Mintlify skill fetching (legacy)
+├── providers/       # Remote skill providers (GitHub, HuggingFace, Mintlify)
+│   ├── index.ts
+│   ├── registry.ts
+│   ├── types.ts
+│   ├── huggingface.ts
+│   └── mintlify.ts
+├── init.test.ts     # Init command tests
+└── test-utils.ts    # Test utilities
+
+tests/
+├── sanitize-name.test.ts     # Tests for sanitizeName (path traversal prevention)
+├── skill-matching.test.ts    # Tests for filterSkills (multi-word skill name matching)
+├── source-parser.test.ts     # Tests for URL/path parsing
+├── installer-symlink.test.ts # Tests for symlink installation
+├── list-installed.test.ts    # Tests for listing installed skills
+├── skill-path.test.ts        # Tests for skill path handling
+├── wellknown-provider.test.ts # Tests for well-known provider
+└── dist.test.ts              # Tests for built distribution
+```
+
+## Update Checking System
+
+### How `skills check` and `skills update` Work
+
+1. Read `~/.agents/.skill-lock.json` for installed skills
+2. For each skill, get `skillFolderHash` from lock file
+3. POST to `https://add-skill.vercel.sh/check-updates` with:
+   ```json
+   {
+     "skills": [{ "name": "...", "source": "...", "skillFolderHash": "..." }],
+     "forceRefresh": true
+   }
+   ```
+4. API fetches fresh content from GitHub, computes hash, compares
+5. Returns list of skills with different hashes (updates available)
+
+### Why `forceRefresh: true`?
+
+Both `check` and `update` always send `forceRefresh: true`. This ensures the API fetches fresh content from GitHub rather than using its Redis cache.
+
+**Without forceRefresh:** Users saw phantom "updates available" due to stale cached hashes. The fix was to always fetch fresh.
+
+**Tradeoff:** Slightly slower (GitHub API call per skill), but always accurate.
+
+### Lock File Compatibility
+
+The lock file format is v3. Key field: `skillFolderHash` (GitHub tree SHA for the skill folder).
+
+If reading an older lock file version, it's wiped. Users must reinstall skills to populate the new format.
+
+## Key Integration Points
+
+| Feature                    | Implementation                              |
+| -------------------------- | ------------------------------------------- |
+| `skills add`               | `src/add.ts` - full implementation          |
+| `skills experimental_sync` | `src/sync.ts` - crawl node_modules          |
+| `skills check`             | `POST /check-updates` API                   |
+| `skills update`            | `POST /check-updates` + reinstall per skill |
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Test locally
+pnpm dev add vercel-labs/agent-skills --list
+pnpm dev experimental_sync
+pnpm dev check
+pnpm dev update
+pnpm dev init my-skill
+
+# Run all tests
+pnpm test
+
+# Run specific test file(s)
+pnpm test tests/sanitize-name.test.ts
+pnpm test tests/skill-matching.test.ts tests/source-parser.test.ts
+
+# Type check
+pnpm type-check
+
+# Format code
+pnpm format
+```
+
+## Code Style
+
+This project uses Prettier for code formatting. **Always run `pnpm format` before committing changes** to ensure consistent formatting.
+
+```bash
+# Format all files
+pnpm format
+
+# Check formatting without fixing
+pnpm prettier --check .
+```
+
+CI will fail if code is not properly formatted.
+
+## Publishing
+
+```bash
+# 1. Bump version in package.json
+# 2. Build
+pnpm build
+# 3. Publish
+npm publish
+```
+
+## Adding a New Agent
+
+1. Add the agent definition to `src/agents.ts`
+2. Run `pnpm run -C scripts validate-agents.ts` to validate
+3. Run `pnpm run -C scripts sync-agents.ts` to update README.md

package/skills/find-skills/SKILL.md

@@ -1,133 +1,133 @@
----
-name: find-skills
-description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
----
-
-# Find Skills
-
-This skill helps you discover and install skills from the open agent skills ecosystem.
-
-## When to Use This Skill
-
-Use this skill when the user:
-
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Expresses interest in extending agent capabilities
-- Wants to search for tools, templates, or workflows
-- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
-
-## What is the Skills CLI?
-
-The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
-
-**Key commands:**
-
-- `npx skills find [query]` - Search for skills interactively or by keyword
-- `npx skills add <package>` - Install a skill from GitHub or other sources
-- `npx skills check` - Check for skill updates
-- `npx skills update` - Update all installed skills
-
-**Browse skills at:** https://skills.sh/
-
-## How to Help Users Find Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. The domain (e.g., React, testing, design, deployment)
-2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
-3. Whether this is a common enough task that a skill likely exists
-
-### Step 2: Search for Skills
-
-Run the find command with a relevant query:
-
-```bash
-npx skills find [query]
-```
-
-For example:
-
-- User asks "how do I make my React app faster?" → `npx skills find react performance`
-- User asks "can you help me with PR reviews?" → `npx skills find pr review`
-- User asks "I need to create a changelog" → `npx skills find changelog`
-
-The command will return results like:
-
-```
-Install with npx skills add <owner/repo@skill>
-
-vercel-labs/agent-skills@vercel-react-best-practices
-└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 3: Present Options to the User
-
-When you find relevant skills, present them to the user with:
-
-1. The skill name and what it does
-2. The install command they can run
-3. A link to learn more at skills.sh
-
-Example response:
-
-```
-I found a skill that might help! The "vercel-react-best-practices" skill provides
-React and Next.js performance optimization guidelines from Vercel Engineering.
-
-To install it:
-npx skills add vercel-labs/agent-skills@vercel-react-best-practices
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 4: Offer to Install
-
-If the user wants to proceed, you can install the skill for them:
-
-```bash
-npx skills add <owner/repo@skill> -g -y
-```
-
-The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
-
-## Common Skill Categories
-
-When searching, consider these common categories:
-
-| Category        | Example Queries                          |
-| --------------- | ---------------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind |
-| Testing         | testing, jest, playwright, e2e           |
-| DevOps          | deploy, docker, kubernetes, ci-cd        |
-| Documentation   | docs, readme, changelog, api-docs        |
-| Code Quality    | review, lint, refactor, best-practices   |
-| Design          | ui, ux, design-system, accessibility     |
-| Productivity    | workflow, automation, git                |
-
-## Tips for Effective Searches
-
-1. **Use specific keywords**: "react testing" is better than just "testing"
-2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
-3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
-
-## When No Skills Are Found
-
-If no relevant skills exist:
-
-1. Acknowledge that no existing skill was found
-2. Offer to help with the task directly using your general capabilities
-3. Suggest the user could create their own skill with `npx skills init`
-
-Example:
-
-```
-I searched for skills related to "xyz" but didn't find any matches.
-I can still help you with this task directly! Would you like me to proceed?
-
-If this is something you do often, you could create your own skill:
-npx skills init my-xyz-skill
-```
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```