DOCSEARCHbyAlgolia
Submit Docs

GoSkills

repository·master·Indexed 41 days ago

https://github.com/smallnest/goskills

A command-line and web-based tool for parsing, managing, and executing Claude Skill packages. It integrates with LLMs (OpenAI, DeepSeek, etc.) and supports the Model Context Protocol (MCP) to automate complex tasks using tools like shell execution, Python, and Tavily web searching.

Tokens
10.2K
Snippets
40
Records
53
Agent score
51%

What's inside GoSkills

  1. What is the 'Bash is All You Need' philosophy?

    master
    The project is built on the principle that a single, universal bash tool is more efficient than having many specialized tools. Instead of separate tools for cat, grep, or python, a single tool can execute any shell command. This reduces code complexity and increases flexibility by leveraging existing Unix tools directly.

  2. Choose a structural pattern for a skill

    master

    When defining the content of a skill, select a structural pattern that matches the skill's primary purpose. Common patterns include:

    • Workflow-Based: Best for sequential, step-by-step procedures (e.g., Overview → Workflow Decision Tree → Step 1 → Step 2).
    • Task-Based: Best for tool collections offering various operations (e.g., Overview → Quick Start → Task Category 1 → Task Category 2).
    • Reference/Guidelines: Best for standards or specifications (e.g., Overview → Guidelines → Specifications).
    • Capabilities-Based: Best for integrated systems providing multiple interrelated features (e.g., Overview → Core Capabilities → Feature List).

  3. Organize skill resources using scripts, references, and assets

    master

    When creating a skill in GoSkills, you can bundle different types of resources to guide Claude's behavior or provide tools. Use the following directory structure to organize these resources:

    • scripts/: Contains executable code (e.g., Python, Bash) that performs specific operations. These can be run directly or read by Claude for patching/environment adjustments.
    • references/: Contains documentation, API references, schemas, or guides intended to be loaded into Claude's context to inform its reasoning and process.
    • assets/: Contains files meant to be used in the output Claude produces (e.g., templates, boilerplate, images, fonts) rather than being loaded into the context itself.

    You should delete any of these directories that are not required for your specific skill.

  4. Structure a GoSkills skill using resource directories

    master

    When creating a new skill in GoSkills, you should organize your bundled resources into specific directories based on how Claude interacts with them. This ensures Claude uses the right information for reasoning versus execution.

    Use the following directory structure:

    • scripts/: Contains executable code (e.g., Python, Bash) used for automation or data processing. Claude can read these to understand logic or use them to perform specific operations.
    • references/: Contains documentation, API references, schemas, or guides. These files are intended to be loaded into Claude's context to inform its decision-making and reasoning.
    • assets/: Contains files intended for the output Claude produces, rather than its internal reasoning. This includes templates, boilerplate code, fonts, or images that the user should receive as a result of the skill.

  5. How tool error handling works in GoSkills

    master

    GoSkills uses an LLM-driven error recovery system rather than hardcoded retry logic. When a tool execution fails, the system automatically captures the failure and feeds it back into the conversation history as a tool response. This allows the LLM to use its reasoning capabilities to decide how to recover.

    The recovery workflow:

    1. Log: The error is logged for debugging.
    2. Format: A detailed error message is generated containing the tool name, specific error details, the original arguments used, and recovery suggestions.
    3. Inject: This error message is appended to the conversation history as a message with the tool role.
    4. Recover: The LLM receives this context and chooses a new action (e.g., correcting parameters, using a different tool, or changing its overall approach).
    Tool execution failed: bash
Error details: command failed: cat: /path/to/nonexistent/file.txt: No such file or directory
Tool name: bash
Arguments: {"command": "cat /path/to/nonexistent/file.txt"}

You can try:
1. Retry with different parameters
2. Use a different tool
3. Modify your approach

  6. Use the Web Interface (`agent-web`)

    master

    The agent-web interface provides a modern UI for interacting with GoSkills agents.

    Features:

    • Chat: Real-time conversation with agents.
    • Artifacts: View generated Reports, PPTs, and Podcasts in the browser.
    • History: Replay and review past sessions.
    • Localization: Toggle between English and Chinese.

    To start the interface, run the ./agent-web binary.

    ./agent-web

  7. Use the GoSkills Skill Runner CLI

    master

    The goskills runner simulates the Claude skill usage workflow by discovering available skills and using an LLM to execute them.

    Download Skills

    Download skill packages from GitHub directly to ~/.goskills/skills:

    ./goskills download https://github.com/ComposioHQ/awesome-claude-skills/tree/master/meeting-insights-analyzer

    Run a Skill

    Execute a request using the default OpenAI model (gpt-4o):

    ./goskills run "your request here"

    Execute using a custom model and API base via flags:

    ./goskills run --model deepseek-v3 --api-base https://qianfan.baidubce.com/v2 "your request here"

    Execute with automatic approval (no manual intervention required):

    ./goskills run --auto-approve --model deepseek-v3 --api-base https://qianfan.baidubce.com/v2 "your request here"
    ./goskills run "create an algorithm that generates abstract art"

  9. Choose a structure for your skill documentation

    master

    When writing the SKILL.md file, you should choose a structural pattern that best fits the skill's purpose. Common patterns include:

    1. Workflow-Based: Best for sequential, step-by-step procedures (e.g., a decision tree for reading → creating → editing).
    2. Task-Based: Best for tool collections offering different operations (e.g., Merge PDFs → Split PDFs → Extract Text).
    3. Reference/Guidelines: Best for standards, brand guidelines, or technical specifications (e.g., Colors → Typography).
    4. Capabilities-Based: Best for integrated systems providing multiple interrelated features.

    Most effective skills mix and match these patterns (e.g., starting with a task-based overview and adding a workflow for complex operations).

  10. LLM recovery strategies for tool failures

    master

    When the system reports a tool error, the LLM typically employs one of three recovery strategies to continue the task:

    1. Parameter Correction: The LLM identifies that the input was slightly wrong (e.g., a typo in a file path) and retries with the corrected value.
    2. Alternative Commands: If a specific command fails (e.g., cat failing due to permissions), the LLM tries a different command to achieve the same goal (e.g., find to locate the file first).
    3. Approach Modification: If the current path is blocked, the LLM changes its strategy entirely (e.g., creating a file instead of trying to read a non-existent one).
    // Example: Parameter Correction
{
  "tool": "bash",
  "arguments": {"command": "cat ./existing-file.txt"}
}

// Example: Alternative Commands
{
  "tool": "bash",
  "arguments": {"command": "find . -name '*.txt' | head -10"}
}

// Example: Approach Modification
{
  "tool": "bash",
  "arguments": {"command": "echo 'new content' > /path/to/file.txt"}
}

  11. Install GoSkills

    master

    You can install GoSkills using Homebrew or by compiling from source.

    Using Homebrew

    brew install smallnest/goskills/goskills

    Or add the tap first:

    brew tap smallnest/goskills
brew install goskills

    From Source

    git clone https://github.com/smallnest/goskills.git
cd goskills
make
    brew install smallnest/goskills/goskills

  12. Configure LLM Environment Variables

    master

    GoSkills requires an LLM integration to execute skills. It primarily uses the OpenAI API format. You can use standard OpenAI or any OpenAI-compatible API (like DeepSeek).

    Standard OpenAI Setup

    export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

    DeepSeek or OpenAI-Compatible Setup

    To use DeepSeek or another provider, set the OPENAI_API_BASE and OPENAI_MODEL variables:

    export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="deepseek-chat"
export OPENAI_API_BASE="https://api.deepseek.com/v1"
    export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL="deepseek-chat"
export OPENAI_API_BASE="https://api.deepseek.com/v1"