Learn And Skill

Learn and Skill

Generate technology-specific skills by researching official documentation and synthesizing findings into a complete, well-structured skill package.

About Generated Skills

Generated skills follow the flutter-expert reference-table pattern:

• Concise SKILL.md (<100 lines) acting as an index
• Topic-specific reference files in references/ loaded on demand
• Frontmatter with CSO-optimized description for discoverability
• Quick Reference table and Constraints section

All generated skills conform to skill-creator conventions:

• Only name and description in frontmatter
• Progressive disclosure (metadata -> body -> references)
• No extraneous files (no README, CHANGELOG, etc.)
• Bundled resources only in references/ (no scripts/ or assets/ unless justified)

Skill Creation Process

Creating a documentation skill involves these steps:

1. Understand the technology with requirements gathering 2. Research the technology (Context7 MCP + web search) 3. Organize findings into topic areas 4. Initialize and generate the skill 5. Package the skill 6. Iterate based on real usage

Follow these steps in order.

Step 1: Understand the Technology

Ask the user (max 2-3 questions):

Auto-detect technology type to guide research depth:

• Framework (Flutter, Next.js, Django): broad coverage
• Library (Riverpod, Axios, Lodash): focused API coverage
• Tool (Docker, Webpack, ESLint): config and CLI focus
• Language (Dart, Rust, Go): syntax, idioms, stdlib

Step 2: Research the Technology

Read references/research-strategy.md for the complete research protocol.

Summary:

• Phase A: Context7 MCP (primary) -> resolve-library-id, then 5x query-docs
• Phase B: Web search (complementary) -> official docs, best practices
• Phase C: Web fetch (gap-filling) -> official pages, GitHub README
• Complete when: 3+ topics with 2+ code examples each, official URL confirmed

Step 3: Organize Findings

Categorize research into 4-8 topic areas. Each becomes a reference file.

Common topics by technology type:

Rules:

• Split topics exceeding 150 lines
• Merge topics under 20 lines
• Each topic needs: explanation, code examples, common pitfalls

Step 4: Initialize and Generate the Skill

4a: Initialize using skill-creator's init script:

~/.agents/skills/skill-creator/scripts/init_skill.py {skill-name} --path {target-path}

4b: Clean up unused template files:

• Delete scripts/, assets/, and example files created by init
• Keep only references/ directory

4c: Write SKILL.md using the reference-table pattern. Read references/output-templates.md for exact templates.

Key sections:

• Frontmatter with CSO-optimized description
• Overview (1-2 sentences)
• Reference table (topics -> files -> "Load When" guidance)
• Quick Reference (5-10 most used items as table)
• Constraints (MUST DO / MUST NOT DO from official best practices)
• Target: under 100 lines total

4d: Write reference files in references/:

• One .md per topic area
• Each: overview + code examples + common pitfalls
• Under 200 lines each
• Code blocks with correct language tags
• Source attribution where applicable

Step 5: Package the Skill

5a: Validate:

~/.agents/skills/skill-creator/scripts/quick_validate.py {skill-path}

Read references/quality-checklist.md for additional validations.

5b: Package:

~/.agents/skills/skill-creator/scripts/package_skill.py {skill-path}

Step 6: Iterate

After real usage, improve the skill: 1. Use the generated skill on real tasks 2. Notice gaps or inaccuracies 3. Update reference files or SKILL.md 4. Re-validate and re-package

Source Reliability Hierarchy

1. Context7 MCP - pre-vetted documentation with source URLs 2. Official documentation - .dev, .io, official repos 3. GitHub README - project repository 4. Reputable guides - core team articles, official blog posts

Never generate code examples from memory when official examples exist. Always prefer official examples over custom illustrations.

learn-and-skill

Meta-skill for Claude Code that researches any technology and generates a complete documentation skill from official sources.

Give it a technology name ("Redis", "Riverpod", "Tailwind CSS") and it produces a ready-to-use skill with SKILL.md and reference files — all sourced from real documentation, not hallucinated content.

How It Works

1. You ask for a skill about any technology 2. It researches via Context7 MCP + web search to gather official documentation 3. It organizes findings into topic areas with code examples 4. It generates a complete skill following the flutter-expert reference-table pattern 5. It validates and packages the skill using skill-creator scripts

Generated Skill Structure

{technology}-docs/
├── SKILL.md                    # Concise index (<100 lines)
│   ├── Reference table         # Topics → files → load triggers
│   ├── Quick Reference         # 5-10 most used items
│   └── Constraints             # MUST DO / MUST NOT DO
└── references/
    ├── {topic-1}.md            # Code examples + pitfalls
    ├── {topic-2}.md
    └── ...

Usage

You: /learn-and-skill
You: "I want a skill for Express.js"

Claude will research Express.js, generate the skill, validate it, and package it.

Prerequisites

• skill-creator installed at ~/.agents/skills/skill-creator/
• Context7 MCP server configured in Claude Code

Installation

Copy the learn-and-skill/ folder to your skills directory:

cp -r learn-and-skill ~/.agents/skills/

Source Reliability

Research follows a strict hierarchy to prevent hallucinated content:

1. Context7 MCP — pre-vetted documentation with source URLs 2. Official documentation — project websites and repos 3. GitHub README — project repository 4. Reputable guides — core team articles and blog posts

All generated code examples come from official sources, never from model memory.

License

MIT

Output Templates

Templates for generated skill files. Follow the flutter-expert pattern: concise SKILL.md as an index with reference files for each topic.

Generated SKILL.md Template

Frontmatter

---
name: {skill-name}
description: >-
  {Technology} development patterns, API reference, and best practices.
  Use when working with {Technology} for: {trigger scenario 1},
  {trigger scenario 2}, {trigger scenario 3}. Covers {topic 1},
  {topic 2}, {topic 3}.
---

Body

# {Technology Title}

{1-2 sentence overview: what it is and what problems it solves.}

## Reference Guide

Load detailed guidance based on context:

| Topic | Reference | Load When |
|-------|-----------|-----------|
| {Topic} | `references/{topic-file}.md` | {Trigger context} |

## Quick Reference

| {Column 1} | {Column 2} |
|-------------|-------------|
| {Item} | {Description} |

## Constraints

### MUST DO
- {Technology-specific best practice from official docs}

### MUST NOT DO
- {Technology-specific anti-pattern from official docs}

Generated Reference File Template

# {Topic Title}

## Overview

{2-3 sentences explaining this aspect of the technology.}

## {Subtopic 1}

{Brief explanation.}

\`\`\`{language}
{Code example from official docs or standard pattern}
\`\`\`

## {Subtopic 2}

{Brief explanation.}

\`\`\`{language}
{Code example}
\`\`\`

## Common Pitfalls

- **{Pitfall 1}**: {Why it happens and how to avoid it}
- **{Pitfall 2}**: {Why it happens and how to avoid it}

Adaptations by Technology Type

Framework (Flutter, Next.js, Django)

• Topics: setup/structure, routing, state management, data layer, testing, deployment
• Reference table: 6-8 entries
• Quick reference: core architectural decisions

Library (Riverpod, Axios, Lodash)

• Topics: installation, core API, patterns, integration, advanced usage
• Reference table: 4-6 entries
• Quick reference: main function/class signatures

Tool (Docker, Webpack, ESLint)

• Topics: installation, configuration, CLI commands, workflows, plugins
• Reference table: 4-6 entries
• Quick reference: CLI command cheat sheet

Language (Dart, Rust, Go)

• Topics: syntax basics, idioms, standard library, ecosystem, tooling
• Reference table: 6-10 entries
• Quick reference: syntax cheat sheet or key constructs

Description Writing Guide

The description is the primary triggering mechanism. It must:

1. Name the technology clearly in the first sentence 2. List trigger scenarios with "Use when..." phrasing 3. Mention key topics covered by the skill 4. Stay under 1024 characters

Good example:

Redis data store patterns, commands, and best practices. Use when working
with Redis for: caching strategies, pub/sub messaging, data structures,
session management, or cluster configuration. Covers connection setup,
common commands, data types, persistence, and performance optimization.

Quality Checklist

Validation criteria for generated documentation skills. Run all checks before packaging.

Structural Validation

• [ ] Passes: ~/.agents/skills/skill-creator/scripts/quick_validate.py {path}
• [ ] name: kebab-case, <= 64 chars, matches directory name
• [ ] description: <= 1024 chars, no angle brackets
• [ ] description: includes technology name
• [ ] description: lists trigger scenarios ("Use when...")
• [ ] description: mentions key topic areas covered
• [ ] SKILL.md body: under 100 lines (reference-table style)
• [ ] No extraneous files (no README.md, CHANGELOG.md, etc.)
• [ ] Only references/ directory exists (no scripts/ or assets/)

Reference Files

• [ ] Every file in reference table exists in references/
• [ ] Every file in references/ appears in reference table
• [ ] Each file under 200 lines
• [ ] Each file has >= 1 code example with correct language tag
• [ ] File names use kebab-case
• [ ] No content duplicated between files or with SKILL.md

Content Quality

• [ ] At least 3 code examples total across all reference files
• [ ] Code uses correct syntax for the documented version
• [ ] Constraints are technology-specific, not generic advice
• [ ] Quick Reference has 5-10 entries
• [ ] Examples are practical, not trivial hello-world (unless for setup)

Anti-Hallucination

• [ ] Every API method/function was found in research sources
• [ ] Function signatures match official documentation
• [ ] Configuration options come from official docs, not assumed
• [ ] Code examples originate from Context7 or official sources
• [ ] Uncertain details marked with [VERIFY] comment
• [ ] Source URLs recorded for key information

Final Steps

Run validation:

~/.agents/skills/skill-creator/scripts/quick_validate.py {skill-path}

Run packaging:

~/.agents/skills/skill-creator/scripts/package_skill.py {skill-path}

Manual verification:

• Can the generated skill be understood without reading learn-and-skill?
• Does it cover what a developer needs to USE the technology?
• Would another Claude instance find this skill helpful?

Research Strategy

Protocol for researching technology documentation. Always prefer confirmed, reliable sources over generated content.

Phase A: Context7 MCP (Primary Source)

A1: Resolve Library ID

Call resolve-library-id with:

• libraryName: the technology name (e.g., "riverpod", "express", "redis")
• query: "documentation API reference patterns best practices for {technology}"

Select the best result based on:

• Source Reputation: prefer High or Medium
• Benchmark Score: prefer 80+ (excellent coverage)
• Code Snippet count: prefer >50 (good documentation depth)

If no match found, skip to Phase B (web search becomes primary).

A2: Query Documentation

Execute up to 5 query-docs calls with focused queries:

1. "Getting started setup installation quickstart" 2. "Core concepts API reference main features" 3. "Common patterns best practices recommended approach" 4. "Advanced features configuration options" 5. "Error handling debugging troubleshooting common mistakes"

For each response:

• Record the returned markdown content and code examples
• Record all source URLs
• Map content to topic areas from Step 3

A3: Assess Coverage

After Context7 queries, evaluate:

• Which topics have >= 2 code examples? (well covered)
• Which are missing or thin? (need web search)
• Any official URLs identified to fetch directly?

Phase B: Web Search (Complementary)

B1: Find Official Documentation

Search: "{technology} official documentation site" Verify domain matches known official patterns.

B2: Find Best Practices

Search: "{technology} best practices patterns {current year}" Filter for results from official project sources.

B3: Fill Coverage Gaps

For each gap identified in A3: Search: "{technology} {gap-topic} guide examples"

Phase C: Web Fetch (Gap-Filling)

C1: Official Documentation Page

If an official URL was identified, fetch it with a focused prompt requesting core concepts, API reference, and code examples.

C2: GitHub README

If the project has a repository, fetch the README for installation instructions and feature overview.

C3: Selective Deep Dives

• Only for uncovered topic areas
• Only from official documentation domains
• Maximum 3 additional fetches

Research Completeness Criteria

Research is sufficient when ALL are met:

• [ ] Technology purpose and positioning understood
• [ ] Installation/setup process documented
• [ ] At least 3 topic areas have >= 2 code examples each
• [ ] Core API or primary concepts documented
• [ ] At least one common pitfall or best practice identified
• [ ] Official documentation URL confirmed and recorded

If criteria cannot be met (obscure technology, no Context7 support):

• Inform the user that research coverage may be limited
• Offer to create a minimal skill based on available information
• Ask the user to provide documentation URLs or content directly