diff --git a/skills/tinyskills/SKILL.md b/skills/tinyskills/SKILL.md new file mode 100644 index 00000000..79e4686b --- /dev/null +++ b/skills/tinyskills/SKILL.md @@ -0,0 +1,314 @@ +--- +name: self-improve-with-tinyfish +description: Enables Hermes to create new reusable skills for itself by researching live web sources with TinyFish Search and Fetch, analyzing source coverage, writing SKILL.md files, and installing them into Hermes memory. Use when the user asks Hermes to learn, teach itself, upgrade itself, or save a reusable capability. +--- + +# Self-Improve With TinyFish + +## When To Use +Use this skill when the user asks Hermes to: +- Learn a new tool, API, framework, workflow, or domain for future tasks. +- Create, install, or improve a reusable Hermes skill. +- Research official docs and examples before writing procedural memory. +- “Teach yourself,” “upgrade yourself,” or “make a skill for this.” + +Do not use this skill for ordinary one-off answers unless the user explicitly wants a saved skill. + +## Core Workflow +1. Acknowledge the learning request. +2. Send a short progress update: “I’ll research this with TinyFish and create a reusable skill.” +3. Extract a clean skill topic from the user request. + - Preserve constraints such as “check official docs,” “cover all endpoints,” “focus on errors,” or “make it production-ready.” +4. Search with TinyFish. + - Prefer the TinyFish CLI when installed. + - Use curl or Python with `urllib.request` only as fallback. + - Run multiple targeted searches. + - Prefer official docs and authoritative examples first. + - Do not invent URLs. +5. Analyze search results. + - Review titles, snippets, URLs, site names, and ranks. + - Decide whether the current sources cover setup, main workflow, edge cases, and validation. + - If coverage is weak, run follow-up searches before fetching. +6. Fetch selected URLs. + - Use TinyFish Fetch for known URLs. + - Fetch 3-8 strong sources by default. + - Prefer markdown output. + - Continue if one URL fails; replace critical failed sources with another search result. +7. Write the new skill. + - Create a focused `SKILL.md`. + - Make it procedural and reusable. + - Include gotchas, defaults, validation, and references. + - Do not dump raw docs. +8. Install and verify. + - Save the generated skill using Hermes skill management. + - Verify with `skill_view` or `skills list`. + - Tell the user only the skill name and that it can be used going forward. + +## TinyFish Bash Defaults +Assume `TINYFISH_API_KEY` is available in the environment. + +Before using TinyFish, check: + +```bash +test -n "$TINYFISH_API_KEY" || echo "TINYFISH_API_KEY is not set" +``` + +If it is missing, ask the user to configure it. + +If the CLI is missing, install it when appropriate: + +```bash +npm install -g @tiny-fish/cli +``` + +The CLI outputs JSON by default. Use `--pretty` only for human inspection, not for parsing. + +Use Python for URL encoding and JSON extraction when shell quoting would be fragile or when the CLI is unavailable. + +## Search Pattern +Use TinyFish Search when you need ranked web results, snippets, and URLs. + +### Preferred CLI search + +```bash +tinyfish search query "{topic} official documentation" +``` + +### Geo/language-targeted search + +```bash +tinyfish search query "best restaurants" --location "FR" --language "fr" +``` + +### Parse CLI JSON + +```bash +tinyfish search query "{topic} official documentation" \ + | python3 -c 'import json,sys; data=json.load(sys.stdin); [print(f"{r.get(\"position\")}. {r.get(\"title\")} -> {r.get(\"url\")}") for r in data.get("results", [])[:10]]' +``` + +### Fallback raw API search + +```python +python3 - <<'PY' +import json +import os +import urllib.parse +import urllib.request + +query = "{topic} official documentation" +api_key = os.environ["TINYFISH_API_KEY"] +url = "https://api.search.tinyfish.ai?query=" + urllib.parse.quote(query) + +req = urllib.request.Request(url, headers={"X-API-Key": api_key}) +with urllib.request.urlopen(req, timeout=15) as res: + data = json.load(res) + +for r in data.get("results", [])[:10]: + print(json.dumps({ + "position": r.get("position"), + "site_name": r.get("site_name"), + "title": r.get("title"), + "url": r.get("url"), + "snippet": r.get("snippet"), + }, ensure_ascii=False)) +PY +``` + +Run searches like: +- `{topic} official documentation` +- `{topic} API reference` +- `{topic} quickstart examples` +- `site:github.com {topic} examples issues` +- `{topic} common errors best practices` + +For API skills, add: +- `{topic} authentication` +- `{topic} SDK reference` +- `{topic} CLI reference` +- `{topic} rate limits errors` + +For framework skills, add: +- `{topic} production best practices` +- `{topic} testing debugging deployment` + +## Search Analysis Loop +After each search pass, decide: +- Do I have at least one official source? +- Do I have setup or authentication covered? +- Do I have the main workflow covered? +- Do I have enough code or command examples? +- Do I have likely mistakes and validation checks? +- Are there duplicate or low-value sources I should ignore? + +If no, send a short user update and run targeted follow-up searches. + +Example update: +“I found the official docs and examples. I'm checking for pitfalls and validation guidance before writing the skill.” + +## Source Selection Rules +Prefer sources in this order: +1. Official docs, API references, quickstarts. +2. Official examples, cookbook repos, templates. +3. GitHub issues/discussions with concrete failure modes. +4. Stack Overflow answers for specific errors. +5. High-quality technical blog posts that fill real gaps. + +Reject: +- Marketing pages without implementation detail. +- Duplicate docs pages. +- Outdated sources when official docs exist. +- Shallow posts that only repeat generic concepts. + +Default to 3-8 fetched URLs total. + +## Fetch Pattern +Use TinyFish Fetch when you already know the URLs and need clean extracted content. + +### Preferred CLI fetch + +```bash +tinyfish fetch content get --format markdown "https://example.com/article" +``` + +### Fetch multiple URLs in one call + +```bash +tinyfish fetch content get --format markdown \ + "https://site-a.com" \ + "https://site-b.com" \ + "https://site-c.com" +``` + +### Include extracted links when useful + +```bash +tinyfish fetch content get --links --image-links "https://example.com" +``` + +### Fallback raw API fetch + +```python +python3 - <<'PY' +import json +import os +import urllib.request + +api_key = os.environ["TINYFISH_API_KEY"] +urls = [ + "https://example.com/docs", + "https://example.com/quickstart", +] + +body = json.dumps({ + "urls": urls, + "format": "markdown", +}).encode() + +req = urllib.request.Request( + "https://api.fetch.tinyfish.ai", + data=body, + headers={ + "X-API-Key": api_key, + "Content-Type": "application/json", + }, + method="POST", +) + +with urllib.request.urlopen(req, timeout=150) as res: + data = json.load(res) + +for page in data.get("results", []): + print("\n---SOURCE---") + print("URL:", page.get("url")) + print("FINAL:", page.get("final_url")) + print("TITLE:", page.get("title")) + print("TEXT:") + print((page.get("text") or "")[:12000]) + +for err in data.get("errors", []): + print("\n---FETCH ERROR---") + print(err) +PY +``` + +Fetch returns per-URL errors in `errors[]`. Do not fail the whole run because one source failed. + +## Writing The Generated Skill +The generated skill must be raw Markdown beginning with frontmatter: + +```markdown +--- +name: concise-kebab-case-name +description: Third-person description of what the skill does and when to use it. +--- +``` + +The description must include: +- What the skill does. +- When Hermes should use it. + +Use this structure unless the topic requires a better one: +- `# Skill Title` +- `## When To Use` +- `## Core Workflow` +- `## Defaults` +- `## Key Patterns` +- `## Gotchas` +- `## Validation` +- `## References` + +Write for future Hermes behavior, not for a human tutorial. + +Include: +- Exact commands or code only when they change execution. +- Defaults and decision rules. +- Gotchas that Hermes is likely to miss. +- Validation checks before finishing. +- Source URLs in References. + +Avoid: +- Raw search dumps. +- Long copied docs sections. +- Generic “best practices” filler. +- Unverified claims. +- Menus of options without a recommended default. + +## Installing The Skill +After writing the skill: +- Save it using Hermes skill management. +- Verify the skill exists with `skill_view` or equivalent. +- If verification fails, repair the frontmatter or skill path. +- Send the user a concise completion message. + +Completion message: +- `Done, I added the skill and can use it going forward.` + +Do not send the full `SKILL.md` unless the user asks. + +## User Progress Updates +During long runs, send concise updates: +- “I’ll research this with TinyFish and create a reusable skill.” +- “Searching official docs and examples...”. +- “I found 6 candidate sources and am checking coverage.” +- “Fetching the best sources...” +- “Writing the skill...”. +- “Installing and verifying it...”. +- “Done, I added the skill and can use it going forward.” + +Do not expose raw JSON, terminal logs, or full source text in chat. + +## Validation Checklist +Before finalizing, confirm: +- `TINYFISH_API_KEY` was available. +- Search results included at least one authoritative source. +- Fetched content was actually used. +- Frontmatter has `name` and `description`. +- Skill name is kebab-case. +- Skill includes workflow, defaults, gotchas, validation, and references. +- The saved skill can be viewed by Hermes. + +## References +- https://docs.tinyfish.ai/search-api +- https://docs.tinyfish.ai/fetch-api +- https://docs.tinyfish.ai/for-coding-agents