The Mistakes of Agent-Skills: A Lightweight AI Framework

1. Purpose and main functionality

Agent‑Skills is a lightweight framework for building AI agents from small, reusable modules called skills. Each skill implements a single capability—e.g., calling an API, transforming data, or generating text with a language model—and exposes a run(input, context) method. The framework emphasizes:

• Modularity – Skills are isolated in their own files and can be added, removed, or replaced without changing the core agent code.
• Reusability – The same skill can be shared across different agents or projects.
• Cross‑language orchestration – The repository ships a Node.js runtime, but the skill interface is defined so that wrappers in Python or other languages can invoke the skills.
• Simple configuration – A config/ directory holds JSON files that enable or disable skills via environment variables or direct edits.

Typical scenarios include chat‑bots that need external data (e.g., weather, calendar), personal assistants that combine retrieval‑augmented generation with domain logic, and research prototypes that explore multi‑step reasoning pipelines.

---

2. Installation and setup

Prerequisites

The framework does not depend on proprietary cloud services. Optional steps for GitHub Codespaces and AWS SageMaker assume you have accounts with those providers.

Clone the repository

git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills

Local installation (Node‑only)

1. Install exact dependency versions:

   npm ci
   

2. Run the test suite to confirm the environment:

   npm test
   

3. Start the demonstration server:

   npm run demo
   

The server listens on port 3000 and exposes a POST /run endpoint that accepts a JSON payload with a skill name and input.

Optional Python wrapper

cd python
pip install -r requirements.txt
python -m agent_skills_demo

The wrapper communicates with the Node process over a local WebSocket; protocol details are in python/README.md.

Cloud deployment options

GitHub Codespaces

1. Open the repository on GitHub and choose Code → Open with Codespaces.
2. The devcontainer defined in .devcontainer/Dockerfile installs Node, Python, and runs the test suite automatically.
3. Inside the Codespace terminal, execute npm run demo. GitHub forwards the service to a public URL.

AWS SageMaker (or similar managed notebook)

1. Launch a Studio notebook instance with a Conda environment that includes Node 18 and Python 3.9.
2. Clone the repository into the notebook’s file system.
3. Run npm ci and npm run demo.
4. Use SageMaker’s lifecycle configuration or an SSH tunnel to expose port 3000.

Containerised production

A Dockerfile is provided that builds an image exposing port 3000. Build the image, push it to a container registry, and run it on any platform that supports Docker (e.g., AWS ECS, Google Cloud Run, Azure Container Apps).

---

3. Core components and creating a skill

Repository layout (high‑level)

agent-skills/
├─ config/          # JSON/YAML files that enable skills
├─ skills/          # Individual skill modules
│   ├─ weather.js
│   ├─ calendar.js
│   └─ llm.js
├─ agent/           # Orchestration logic
│   ├─ Agent.js
│   └─ SkillRegistry.js
├─ python/          # Optional wrapper
├─ tests/           # Jest test suite
├─ Dockerfile
└─ package.json

Key modules

Defining a new skill (Node example)

Create skills/translate.js:

// skills/translate.js
const fetch = require('node-fetch');

class TranslateSkill {
  constructor({ apiKey }) {
    this.apiKey = apiKey;
  }

  async run(input, context) {
    const response = await fetch('https://api.example.com/translate', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ text: input.text, target: input.targetLang }),
    });
    const data = await response.json();
    return { translation: data.translatedText };
  }
}

module.exports = TranslateSkill;

Registering the skill

Add the skill to a configuration file, e.g., config/skills.json:

{
  "enabledSkills": ["weather", "llm", "translate"],
  "translate": {
    "apiKey": "YOUR_TRANSLATE_API_KEY"
  }
}

When the agent starts, it reads this file, instantiates TranslateSkill with the supplied API key, and registers it under the name "translate".

Invoking a skill through the agent

With the demo server running on http://localhost:3000, send a request:

curl -X POST http://localhost:3000/run \
  -H "Content-Type: application/json" \
  -d '{
        "skill": "translate",
        "input": { "text": "Hello, world!", "targetLang": "es" }
      }'

Expected response:

{
  "result": { "translation": "¡Hola, mundo!" }
}

Using external language‑model APIs (fine‑tuning)

The llm.js skill forwards calls to any OpenAI‑compatible endpoint. To use a fine‑tuned model:

1. Prepare a JSONL dataset according to the provider’s specification.

2. Run the provider’s CLI, for example:

   openai api fine_tunes.create -t dataset.jsonl -m davinci
   

3. Update the skill configuration with the new model identifier:

   {
     "llm": {
       "apiKey": "YOUR_OPENAI_KEY",
       "model": "ft-custom-2024-09-01"
     }
   }
   

The LLMSkill will then call the fine‑tuned model for subsequent requests. The repository does not impose a particular training pipeline; it simply passes the model name to the API.

---

4. Example applications and tutorials

Official quick‑start demo

The README.md includes a step‑by‑step guide:

1. Clone the repository.
2. Enable the weather and llm skills via config/quickstart.json.
3. Run npm run demo.
4. Open http://localhost:3000/ui to use a minimal web UI that sends requests to the /run endpoint.

The UI displays the conversation flow and logs the skill chain in the console.

Notebook‑style tutorial

examples/agent_workflow.ipynb demonstrates:

• Loading the agent from Python using the wrapper.
• Registering a custom skill at runtime.
• Executing a multi‑step conversation where the agent calls the calendar skill and then the llm skill for a summary.

Run the notebook locally:

cd examples
jupyter notebook agent_workflow.ipynb

A badge in the repository’s README links to a pre‑configured Google Colab notebook that performs the same steps in the cloud.

Sample projects

• agent‑skills‑voice‑assistant – A minimal voice‑controlled assistant that combines a speech-to-text skill, the llm skill for intent parsing, and the calendar skill for scheduling. Includes a Docker Compose file that wires the components together.
• agent‑skills‑ecommerce‑bot – Shows how to chain a product‑search skill with an LLM‑based recommendation skill to build a simple shopping assistant.

Both projects are located in the examples/ directory and can be launched with the provided Docker commands.

---

This guide covers the purpose, installation, core architecture, skill development, and available examples for the addyosmani/agent‑skills repository. Use the sections that match your workflow—local development, Python integration, or containerised deployment—to get the framework running quickly and reliably.