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.