skills.rest
werlang
werlangCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

guia-readme

Transforms section READMEs into structured didactic reference guides in PT-BR.

5|Updated Jun 7, 2022
Search Tags:#documentation#markdown#readme#teaching#pt-br#course material#didactic guide
One-click install
npx skills add https://github.com/werlang/pw1 --skill guia-readme-werlang
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: guia-readme
Source: https://github.com/werlang/pw1/tree/main/.agents/skills/guia-readme
Command: npx skills add https://github.com/werlang/pw1 --skill guia-readme-werlang

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Course section READMEs often become either too thin to consult after class or bloated with repeated explanations, outdated exercise references, and examples that no longer match the real code. This Skill turns them into consistent didactic guides aligned with the actual files in the repository. ## Core Features & Use Cases - Guide structuring by material type: Provides distinct outlines for conceptual references, practical guides, exercise statements, and API/back-end documentation. - Didactic writing rules in PT-BR: Enforces concept-before-example progression, short executable examples, common-error sections, and respect for the pedagogical ceiling of each section. - Exercise and slide synchronization: Keeps exercise paths, titles, and references consistent between READMEs and slides, removing stale lists when exercises are replaced. - Use Case: A teacher revises the README of a DOM manipulation section: the Skill guides reading the real example files, restructuring the content with the template, updating exercise links, and validating the result against the checklist. ## Quick Start Use the guia-readme skill to rewrite the README of the current course section as a didactic reference guide in PT-BR, keeping examples and exercise paths synchronized with the real files.

Frequently Asked Questions about guia-readme

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I turn a course section README into a didactic guide?▼

Read the current README and the real example files first, then pick the matching structure (conceptual reference, practical guide, exercise statement, or API doc) and rewrite the content in PT-BR with concepts before examples. Finish by validating against the included checklist.

What structure should a teaching README follow?▼

The recommended structure is: overview, fundamental concepts, basic syntax or flow, common variations, a practical example, repository examples, proposed exercises, frequent errors, best practices, and a summary. The README-TEMPLATE.md file provides this skeleton as a starting point.

How do I keep exercise references synchronized with slides?▼

Describe each exercise's core challenge in one line, use relative links to real paths, and remove old exercise lists when they are replaced. After editing, search the guide and corresponding slides for stale paths, removed titles, and outdated terms.

When should I not expand a README into a full guide?▼

Do not expand content beyond the section's pedagogical ceiling or anticipate future topics just to improve a solution artificially. The guide should be more complete than a slide but shorter than a book chapter, without repeating the same idea to add length.

Does this approach work for API or back-end documentation?▼

Yes, there is a dedicated structure for API and back-end material covering files and responsibilities, input validation, operation sequence, responses and HTTP codes, expected errors, and security or session concerns.

Related Skills

Explore More Education & Research Skills→
haryelramalhoharyelramalho

scaffold-exercises

Create exercise directory structures with lint-safe readmes and variant folders.

Community
Intermediate
Mr-Q526Mr-Q526
23

ppt-english-lesson

Generate structured English classroom PPT decks with deck.json and PPTX export.

Community
Intermediate
hw-native-syshw-native-sys
11

ascendc-code-review

Audit C/C++ code snippets for safety risks using hypothesis-testing analysis.

Official
Advanced
az9713az9713
4

lecture-transcript-slide-matcher

Align timestamped lecture transcripts with PDF slides into interactive HTML study guides.

Community
Intermediate