reduced TOOLS.md to reduce token usage and fixed avail skills missing location

Author: dev-dhg

cmd/yaocc/init.go

@@ -41,6 +41,7 @@ func runInit() {
 	createFileFromTemplate(p("USER.md"), "USER.md")
 	createFileFromTemplate(p("BOOTSTRAP.md"), "BOOTSTRAP.md")
 	createFileFromTemplate(p("MEMORY.md"), "MEMORY.md")
+	createFileFromTemplate(p("SKILLS_TUTORIAL.md"), "SKILLS_TUTORIAL.md")
 
 	// 3. Create sample cron skill
 	if err := os.MkdirAll(p("skills/cron"), 0755); err != nil {

cmd/yaocc/skills.go

@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"os"
+	"path/filepath"
 	"sort"
 	"strings"
 
@@ -146,6 +147,44 @@ func runSkills(args []string) {
 			fmt.Printf("  - %s -> %s\n", name, path)
 		}
 
+	case "get":
+		// Usage: yaocc skills get <name>
+		if len(args) < 2 {
+			fmt.Println("Usage: yaocc skills get <name>")
+			return
+		}
+		name := args[1]
+
+		// Check if it's a registered skill
+		if scriptPath, ok := cfg.Skills.Registered[name]; ok {
+			fmt.Printf("Skill '%s' points to script '%s'.\n", name, scriptPath)
+			// Generally, skills documentation will be under the same folder named SKILL.md
+			// Try to automatically read it
+			dir := config.ResolveConfigDir()
+			resolvedScript, _ := resolveSafePath(dir, scriptPath)
+			skillDir := filepath.Dir(resolvedScript)
+			readmePath := filepath.Join(skillDir, "SKILL.md")
+			if content, err := os.ReadFile(readmePath); err == nil {
+				fmt.Printf("\n--- SKILL.md ---\n%s\n", string(content))
+			} else {
+				fmt.Printf("Warning: Could not automatically find SKILL.md near the script at %s\n", readmePath)
+			}
+			return
+		}
+
+		// Otherwise, it might be a built-in skill, or we should look through actual paths.
+		// For built-ins, we can point them to the docs.
+		fmt.Printf("Skill '%s' is not registered as a custom script skill. If it's built-in (e.g. cron, file_manager, websearch), refer to the core documentation or verify the name.\n", name)
+
+	case "tutorial":
+		dir := config.ResolveConfigDir()
+		tutorialPath := filepath.Join(dir, "SKILLS_TUTORIAL.md")
+		if content, err := os.ReadFile(tutorialPath); err == nil {
+			fmt.Printf("\n--- SKILLS_TUTORIAL.md ---\n%s\n", string(content))
+		} else {
+			fmt.Printf("Warning: Could not find SKILLS_TUTORIAL.md at %s. Try running 'yaocc init' to generate it.\n", tutorialPath)
+		}
+
 	case "help":
 		printSkillsHelp()
 
@@ -182,5 +221,7 @@ func printSkillsHelp() {
 	fmt.Println("  register <name> <path>   Register a new skill")
 	fmt.Println("  unregister <name>        Unregister an existing skill")
 	fmt.Println("  list                     List all skills (built-in and registered)")
+	fmt.Println("  get <name>               Read the instructions (SKILL.md) for a skill")
+	fmt.Println("  tutorial                 Read the comprehensive skill creation tutorial")
 	fmt.Println("  <name> [args]            Execute a registered skill")
 }

pkg/agent/agent.go

@@ -443,7 +443,7 @@ func (a *Agent) GetSystemPrompt(provider messaging.Provider) string {
 			sb.WriteString(fmt.Sprintf("\n### %s\n%s\n%s\n", skill.Name, skill.Description, skill.Content))
 		} else {
 			// New behavior: XML manifest
-			sb.WriteString(fmt.Sprintf("  <skill>\n    <name>%s</name>\n    <description>%s</description>\n  </skill>\n", skill.Name, skill.Description))
+			sb.WriteString(fmt.Sprintf("  <skill>\n    <name>%s</name>\n    <description>%s</description>\n    <location>%s</location>\n  </skill>\n", skill.Name, skill.Description, skill.Path))
 		}
 	}
 	sb.WriteString("</available_skills>\n")

pkg/templates/SKILLS_TUTORIAL.md

@@ -0,0 +1,72 @@
+# Skill Creation Tutorial
+
+Here is the comprehensive guide on how to create and register custom skills for YAOCC.
+You can extend your capabilities by creating new "Skills". A skill is simply a set of instructions and examples stored in a markdown file. and sometimes is accompanied by a script (Python, Bash, JS, etc.)(js preferred) that you register as a new command. Before creating a skill verify it doest exist yet using `yaocc skills list`.
+
+### 1. Create the Script and Skill Definition
+First, create the script and the `SKILL.md` file as usual.
+
+ To add a new skill:
+1.  Create a directory: `skills/<skill_name>/`
+2.  Create a file: `skills/<skill_name>/SKILL.md`
+3.  Write the skill definition in frontmatter and instructions in the body.
+
+#### Example: Creating a "Weather" Skill using `file write`
+
+```bash
+yaocc file write skills/weather/SKILL.md "---
+name: weather
+description: Checks the weather of a city.
+---
+# Weather api
+
+To check the weather of a city run
+\`\`\`bash
+yaocc skills weather <city>
+\`\`\`
+```
+### 2. Create script and verify it runs 
+sometimes you can get away only with SKILL.md
+but sometimes you'll need to create the script, in this case
+
+**Note:** You cannot use reserved names like `list`, `register`, `file`, `cron`, etc.
+
+#### Example: Creating a "Weather" Skill script
+1. **Create the script:**
+```bash
+yaocc file write skills/weather/weather.js "console.log(`Weather in \${process.argv[2]}: Sunny`);"
+```
+
+2. **Verify it runs:**
+verify it runs correctly before you register!
+```bash
+yaocc file run skills/weather/weather.js Paris
+```
+
+3. **Register it:**
+Use the `yaocc skills register` command to link a command name to your script.
+very important you can register the skill only after it runs correctly in the previous step
+
+```bash
+yaocc skills register <command_name> <path_to_script>
+```
+example:
+```bash
+yaocc skills register weather skills/weather/weather.js
+```
+
+4. **Use it:**
+You can now use `yaocc skills weather <city>` directly!
+```bash
+yaocc skills weather Paris
+```
+
+5. **List Skills:**
+```bash
+yaocc skills list
+```
+
+6. **Unregister:**
+```bash
+yaocc skills unregister weather
+```

pkg/templates/TOOLS.md

@@ -18,75 +18,21 @@ yaocc skills list
 ## Creating and Using Skills
 You can extend your capabilities by creating new "Skills". A skill is simply a set of instructions and examples stored in a markdown file. and sometimes is accompanied by a script (Python, Bash, JS, etc.)(js preferred) that you register as a new command. Before creating a skill verify it doest exist yet using `yaocc skills list`.
 
-### 1. Create the Script and Skill Definition
-First, create the script and the `SKILL.md` file as usual.
-
- To add a new skill:
-1.  Create a directory: `skills/<skill_name>/`
-2.  Create a file: `skills/<skill_name>/SKILL.md`
-3.  Write the skill definition in frontmatter and instructions in the body.
-
-#### Example: Creating a "Weather" Skill using `file write`
-
-```bash
-yaocc file write skills/weather/SKILL.md "---
-name: weather
-description: Checks the weather of a city.
----
-# Weather api
-
-To check the weather of a city run
-\`\`\`bash
-yaocc skills weather <city>
-\`\`\`
-```
-### 2. Create script and verify it runs 
-sometimes you can get away only with SKILL.md
-but sometimes you'll need to create the script, in this case
-
-**Note:** You cannot use reserved names like `list`, `register`, `file`, `cron`, etc.
-
-#### Example: Creating a "Weather" Skill script
-1. **Create the script:**
+**CRITICAL RULE FOR UNFAMILIAR SKILLS:** If you see a skill in your `<available_skills>` manifest but do not know its precise arguments, you MUST read its documentation first using:
 ```bash
-yaocc file write skills/weather/weather.js "console.log(`Weather in ${process.argv[2]}: Sunny`);"
+yaocc skills get <skill_name>
 ```
+Do not attempt to guess the arguments of a custom skill before reading its `SKILL.md` body.
 
-2. **Verify it runs:**
-verify it runs correctly before you register!
+### Creating a Custom Skill from Scratch
+If the user asks you to create a brand new custom skill, you MUST first read the tutorial to learn the framework mechanics by running:
 ```bash
-yaocc file run skills/weather/weather.js Paris
+yaocc skills tutorial
 ```
+DO NOT attempt to create a custom skill without reading the tutorial first.
 
-3. **Register it:**
-Use the `yaocc skills register` command to link a command name to your script.
-very important you can register the skill only after it runs correctly in the previous step
-
-```bash
-yaocc skills register <command_name> <path_to_script>
-```
-example:
-```bash
-yaocc skills register weather skills/weather/weather.js
-```
-
-4. **Use it:**
-You can now use `yaocc skills weather <city>` directly!
-```bash
-yaocc skills weather Paris
-```
-
-5. **List Skills:**
-```bash
-yaocc skills list
-```
-
-6. **Unregister:**
-```bash
-yaocc skills unregister weather
-```
 
-### 7. Execute Shell Commands
+### Execute Shell Commands
 ```bash
 yaocc exec <command>
 ```