Instruction tuning for skills (#8)

* Instruction tuning for skills

* Tune readme

Author: cramforce

README.md

@@ -177,7 +177,7 @@ const { tools } = await createBashTool({ sandbox: customSandbox });
 
 ## Skills (Experimental)
 
-Skills are modular capabilities that extend agent functionality. Each skill is a directory containing a `SKILL.md` file with instructions and optional scripts.
+[Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) are modular capabilities that extend agent functionality. Each skill is a directory containing a `SKILL.md` file with instructions and optional scripts.
 
 ```typescript
 import {
@@ -187,7 +187,7 @@ import {
 import { ToolLoopAgent } from "ai";
 
 // Discover skills and get files to upload
-const { loadSkill, files, instructions } = await createSkillTool({
+const { skill, files, instructions } = await createSkillTool({
   skillsDirectory: "./skills",
 });
 
@@ -200,46 +200,28 @@ const { tools } = await createBashTool({
 // Use both tools with an agent
 const agent = new ToolLoopAgent({
   model,
-  tools: { loadSkill, ...tools },
+  tools: { skill, ...tools },
 });
 ```
 
+[Full Example](./examples/skills-tool/) and see [Skills.sh for a directory of publicly available skills.](https://skills.sh/)
+
 ### Skill Directory Structure
 
-```
+```text
 skills/
 ├── csv/
-│   ├── SKILL.md      # Required: instructions with YAML frontmatter
-│   ├── analyze.sh    # Optional: scripts the agent can run
-│   └── filter.sh
+│   ├── SKILL.md         # Required: instructions with YAML frontmatter
+│   └── scripts/         # Optional: scripts the agent can run
+│       ├── analyze.sh
+│       └── filter.sh
 └── text/
     ├── SKILL.md
-    └── search.sh
+    └── scripts/
+        └── search.sh
 ```
 
-### SKILL.md Format
-
-```markdown
----
-name: csv
-description: Analyze and transform CSV files
----
-
-# CSV Processing
-
-Use `./skills/csv/analyze.sh <file>` to analyze a CSV file.
-```
-
-### How It Works
-
-1. `createSkillTool` discovers skills and returns:
-   - `loadSkill` - Tool for the agent to load a skill's instructions on demand
-   - `files` - All skill files to pass to `createBashTool`
-   - `instructions` - Extra instructions listing available skills
-
-2. The agent sees skill names in the `loadSkill` tool description
-3. When the agent needs a skill, it calls `loadSkill("csv")` to get detailed instructions
-4. The agent uses `bash` to run scripts from `./skills/csv/`
+See the [example skills](./examples/skills-tool/skills/) for a complete reference.
 
 ## AI Agent Instructions
 

examples/skills-tool/README.md

@@ -26,8 +26,6 @@ The example includes two bash-based skills:
 npx tsx examples/skills-tool/index.ts
 ```
 
-Requires `ANTHROPIC_API_KEY` environment variable.
-
 ## Code Overview
 
 ```typescript

examples/skills-tool/index.ts

@@ -16,7 +16,7 @@ import {
 
 async function main() {
   // Discover skills and get files to upload
-  const { loadSkill, skills, files, instructions } = await createSkillTool({
+  const { skill, skills, files, instructions } = await createSkillTool({
     skillsDirectory: path.join(import.meta.dirname, "skills"),
   });
 
@@ -36,17 +36,17 @@ async function main() {
   const agent = new ToolLoopAgent({
     model: "anthropic/claude-haiku-4.5",
     tools: {
-      loadSkill,
+      skill,
       bash: tools.bash,
     },
     instructions: `You are a data processing assistant with access to skills.
-Use loadSkill to discover how to use a skill, then use bash to run its scripts.
+Use the skill tool to discover how to use a skill, then use bash to run its scripts.
 Skills are located at ./skills/<skill-name>/.`,
     onStepFinish: ({ toolCalls, toolResults }) => {
       if (toolCalls && toolCalls.length > 0) {
         for (const call of toolCalls) {
           console.log(`Tool: ${call.toolName}`);
-          if (call.toolName === "loadSkill" && "input" in call) {
+          if (call.toolName === "skill" && "input" in call) {
             const input = call.input as { skillName: string };
             console.log(`  Loading skill: ${input.skillName}`);
           } else if (call.toolName === "bash" && "input" in call) {

examples/skills-tool/skills/csv/SKILL.md

@@ -12,39 +12,39 @@ Process CSV files using standard bash tools (awk, cut, sort, grep).
 ### analyze.sh
 Get statistics and summary of a CSV file.
 ```bash
-bash /skills/csv/analyze.sh data.csv
+bash /skills/csv/scripts/analyze.sh data.csv
 ```
 
 ### filter.sh
 Filter rows where a column matches a value.
 ```bash
-bash /skills/csv/filter.sh data.csv <column_number> <value>
+bash /skills/csv/scripts/filter.sh data.csv <column_number> <value>
 ```
 
 ### select.sh
 Select specific columns from CSV.
 ```bash
-bash /skills/csv/select.sh data.csv <col1,col2,col3>
+bash /skills/csv/scripts/select.sh data.csv <col1,col2,col3>
 ```
 
 ### sort.sh
 Sort CSV by a column.
 ```bash
-bash /skills/csv/sort.sh data.csv <column_number> [--numeric] [--reverse]
+bash /skills/csv/scripts/sort.sh data.csv <column_number> [--numeric] [--reverse]
 ```
 
 ## Examples
 
 ```bash
 # Show CSV summary
-bash /skills/csv/analyze.sh sales.csv
+bash /skills/csv/scripts/analyze.sh sales.csv
 
 # Filter where column 3 equals "active"
-bash /skills/csv/filter.sh users.csv 3 active
+bash /skills/csv/scripts/filter.sh users.csv 3 active
 
 # Select columns 1, 2, and 4
-bash /skills/csv/select.sh data.csv 1,2,4
+bash /skills/csv/scripts/select.sh data.csv 1,2,4
 
 # Sort by column 2 numerically in reverse
-bash /skills/csv/sort.sh data.csv 2 --numeric --reverse
+bash /skills/csv/scripts/sort.sh data.csv 2 --numeric --reverse
 ```

…amples/skills-tool/skills/csv/analyze.sh …kills-tool/skills/csv/scripts/analyze.shexamples/skills-tool/skills/csv/analyze.sh renamed to examples/skills-tool/skills/csv/scripts/analyze.sh examples/skills-tool/skills/csv/analyze.sh renamed to examples/skills-tool/skills/csv/scripts/analyze.sh

@@ -12,40 +12,40 @@ Process text files using standard bash tools (grep, sed, awk, wc).
 ### stats.sh
 Get statistics about a text file (lines, words, characters).
 ```bash
-bash /skills/text/stats.sh document.txt
+bash /skills/text/scripts/stats.sh document.txt
 ```
 
 ### search.sh
 Search for patterns in text files.
 ```bash
-bash /skills/text/search.sh <file> <pattern> [--count] [--context <lines>]
+bash /skills/text/scripts/search.sh <file> <pattern> [--count] [--context <lines>]
 ```
 
 ### extract.sh
 Extract specific lines or sections from a file.
 ```bash
-bash /skills/text/extract.sh <file> --lines <start>-<end>
-bash /skills/text/extract.sh <file> --between <start_pattern> <end_pattern>
+bash /skills/text/scripts/extract.sh <file> --lines <start>-<end>
+bash /skills/text/scripts/extract.sh <file> --between <start_pattern> <end_pattern>
 ```
 
 ### wordfreq.sh
 Count word frequencies in a text file.
 ```bash
-bash /skills/text/wordfreq.sh document.txt [--top <n>]
+bash /skills/text/scripts/wordfreq.sh document.txt [--top <n>]
 ```
 
 ## Examples
 
 ```bash
 # Get file statistics
-bash /skills/text/stats.sh readme.txt
+bash /skills/text/scripts/stats.sh readme.txt
 
 # Search with context
-bash /skills/text/search.sh log.txt "ERROR" --context 2
+bash /skills/text/scripts/search.sh log.txt "ERROR" --context 2
 
 # Extract lines 10-20
-bash /skills/text/extract.sh file.txt --lines 10-20
+bash /skills/text/scripts/extract.sh file.txt --lines 10-20
 
 # Top 10 most frequent words
-bash /skills/text/wordfreq.sh article.txt --top 10
+bash /skills/text/scripts/wordfreq.sh article.txt --top 10
 ```