Agent-Skills.md

Agent Skills: Learn

Learn from web sources, generate SKILL.md, and store key patterns in soul memory. Trigger keywords: learn, skill-gen, web-learn, documentation, tutorial.

UncategorizedID: genomewalker/cc-soul/learn

Repository

genomewalker/cc-soul
genomewalker
1

Install this agent skill to your local

pnpm dlx add-skill https://github.com/genomewalker/cc-soul/tree/HEAD/skills/learn

Skill Files

Browse the full folder contents for learn.

Download Skill

Loading file tree…

skills/learn/SKILL.md

Skill Metadata

Name
learn
Description
Learn from web sources, generate SKILL.md, and store key patterns in soul memory. Trigger keywords: learn, skill-gen, web-learn, documentation, tutorial.

Learn

[learn] topic|url|repo→discover→fetch→synthesize→SKILL.md+soul

pipeline:
  1. recall: existing knowledge from soul
  2. classify: topic|url|github-repo|npm-pkg|pypi-pkg
  3. discover: WebSearch→candidate sources (if topic)
  4. fetch: API-first→WebFetch fallback→normalize
  5. synthesize: merge sources→SKILL.md with version pin
  6. persist: SKILL.md + triangulated patterns→soul memory

triangulation: promote to memory only if 2+ sources OR 1 canonical
provenance: source, version, retrieved_at, confidence
output: skills/<topic>/SKILL.md + [SOLUTION]/[GOTCHA]/[PATTERN] markers

--global: ~/.claude/skills/<topic>/SKILL.md
--url: skip discovery, fetch directly
--repo: API-first via gh CLI

Usage

/learn <topic>                    # Search web, create project-local skill
/learn <topic> --global           # Save to ~/.claude/skills/
/learn <url>                      # Learn from specific URL
/learn <owner/repo>               # Learn from GitHub repository
/learn <topic> --depth shallow    # Quick overview only
/learn <topic> --depth deep       # Comprehensive with examples

Process

Stage 1: Recall Existing Knowledge

Before any web activity, check what the soul already knows.

chitta recall --query "<topic>" --limit 10

If soul has relevant memories (< 30 days old), ask:

Soul has N memories about <topic>. Refresh from web? (y/N)

Stage 2: Classify Input

| Pattern | Type | Action | |---------|------|--------| | https://... or http://... | URL | Skip to Stage 4 (fetch) | | owner/repo (no dots) | GitHub repo | API-first via gh CLI | | github.com/owner/repo | GitHub URL | Extract owner/repo, use gh | | @scope/package | npm package | npm view + registry API | | Known PyPI name | PyPI package | pip show + PyPI JSON API | | Everything else | Topic | WebSearch discovery |

Stage 3: Discover Sources (Topic Mode)

Run targeted web searches:

WebSearch: "<topic> documentation guide"
WebSearch: "<topic> tutorial best practices"
WebSearch: "<topic> API reference examples"

Rank sources by quality:

  1. Canonical (highest): Official docs, README, API reference
  2. Authoritative: Tutorial sites, conference talks, RFCs
  3. Community: Blog posts (needs triangulation)

Select top 3-5 sources with diversity.

Stage 4: Fetch and Normalize

API-first ingestion (preferred):

For GitHub repos:

gh api repos/<owner>/<repo> --jq '{name, description, language, topics}'
gh api repos/<owner>/<repo>/readme --jq '.content' | base64 -d
gh api repos/<owner>/<repo>/releases/latest --jq '{tag_name, published_at}'

For npm packages:

npm view <package> name version description homepage --json

For PyPI packages:

pip show <package>
# Or: WebFetch "https://pypi.org/pypi/<package>/json"

WebFetch for HTML (fallback):

WebFetch(url, prompt="Extract: 1) What this does, 2) Key concepts,
3) Installation, 4) Core API with examples, 5) Gotchas, 6) Version info")

JS-rendered docs: WebFetch cannot execute JavaScript. If minimal content returned:

[GOTCHA] <url> appears JS-rendered, content may be incomplete.
Falling back to: GitHub README, API endpoints, or package registry.

Stage 5: Synthesize SKILL.md

Generate SKILL.md with required sections:

---
name: <topic>
description: <one-line description>
version: <detected version or "unknown">
retrieved_at: <YYYY-MM-DD>
sources:
  - <url1>
  - <url2>
---

# <Topic>

## Overview
What it is, what problem it solves, when to use it.

## Installation / Setup
Version-pinned commands (npm install x@1.2.3, pip install x==1.2.3).

## Core Concepts
Key abstractions, terminology, mental model.

## Usage Patterns
Code examples for common operations. At least 2 examples.

## API Quick Reference
Key functions/methods with signatures.

## Gotchas and Caveats
Non-obvious behavior. Common mistakes.

## Version Notes
Version this was written for. Breaking changes.

Conflict handling: If new sources contradict soul memories:

[DECISION] <topic>: Web says X, soul says Y. Adopting X because <reason>.
[GOTCHA] <topic>: Previous approach Z no longer recommended as of vN.

Stage 6: Persist

Write SKILL.md:

# Default (project-local)
mkdir -p ./skills/<topic>/
# Write to ./skills/<topic>/SKILL.md

# With --global
mkdir -p ~/.claude/skills/<topic>/
# Write to ~/.claude/skills/<topic>/SKILL.md

Store patterns in soul (triangulation required):

Only promote patterns confirmed by 2+ sources or 1 canonical source:

chitta remember --content "[<topic>:sol] <pattern>"
chitta remember --content "[<topic>:gotcha] <gotcha>"
chitta remember --content "[<topic>:pat] <usage pattern>"

Emit markers for stop-hook:

[SOLUTION] <topic>: <key approach>
[GOTCHA] <topic>: <trap or caveat>
[PATTERN] <topic>: <recurring pattern>

Quality Gate

| Check | Required | If Missing | |-------|----------|------------| | Frontmatter (name, description) | Yes | Add from synthesis | | At least 1 code example | Yes | Fetch more examples | | Gotchas section | Yes | Add "[none discovered]" | | Version-pinned installs | Yes | Pin to latest | | Sources in frontmatter | Yes | Add all URLs | | retrieved_at date | Yes | Add current date |

Output Format

## Learn: <Topic>

### Sources Consulted
1. [Official Docs](<url>) - canonical
2. [Tutorial](<url>) - authoritative

### Generated
SKILL.md written to: `<path>`
- Sections: N
- Code examples: N
- Version: <version>

### Stored to Soul
- [SOLUTION] N patterns
- [GOTCHA] N warnings
- Triangulation: N/M patterns confirmed by 2+ sources

Examples

Learn a Topic

/learn duckdb

[Recalling existing knowledge...]
Soul has 2 memories about duckdb.

[Discovering sources...]
1. https://duckdb.org/docs/ (canonical)
2. https://duckdb.org/docs/api/python (canonical)
3. https://motherduck.com/blog/duckdb-tutorial (authoritative)

[Synthesizing SKILL.md...]
SKILL.md written to: ./skills/duckdb/SKILL.md
- Sections: 7, Examples: 5, Version: 1.1.3

[SOLUTION] duckdb: in-memory OLAP, pandas integration via .df()
[GOTCHA] duckdb: default memory limit is 80% RAM

Learn from GitHub

/learn duckdb/duckdb

[Fetching via GitHub API...]
  repos/duckdb/duckdb → metadata
  repos/duckdb/duckdb/readme → README
  repos/duckdb/duckdb/releases/latest → v1.1.3

SKILL.md written to: ./skills/duckdb/SKILL.md

Learn from URL

/learn https://docs.pydantic.dev/latest/

[Fetching URL directly...]
[Supplementing with WebSearch for triangulation...]

SKILL.md written to: ./skills/pydantic/SKILL.md

Learn Global

/learn fastapi --global

SKILL.md written to: ~/.claude/skills/fastapi/SKILL.md
Available across all projects.

Error Handling

| Error | Recovery | |-------|----------| | WebSearch no results | Broader query, check spelling | | WebFetch empty/JS-rendered | GitHub README, API, registry | | All sources fail | Report, suggest manual URL | | Recent SKILL.md exists | Ask before overwriting | | GitHub rate limited | WebFetch fallback |

Anti-Patterns

  • Never generate from single blog post without triangulation
  • Never store unverified patterns in soul
  • Never omit discoverable version info
  • Never use latest or unpinned versions in install commands
  • Never skip recall stage
  • Never announce "I found on the web" -- present knowledge naturally

MCP Tools Used

| Tool | Stage | Purpose | |------|-------|---------| | recall | 1 | Check existing knowledge | | remember | 6 | Store confirmed patterns | | learn_insight | 6 | Promote cross-project patterns |