concept-workflow

SKILL.md

Skill: Complete Concept Workflow

Use this skill to create a complete, high-quality concept page from start to finish. This skill orchestrates all five specialized skills in the optimal order:

Resource Curation — Find quality learning resources

Concept Writing — Write the documentation page

Test Writing — Create tests for code examples

Fact Checking — Verify technical accuracy

SEO Review — Optimize for search visibility

When to Use

Creating a brand new concept page from scratch

Completely rewriting an existing concept page

When you want a full end-to-end workflow with all quality checks

For partial tasks, use individual skills instead:

Just adding resources? Use resource-curator

Just writing content? Use write-concept

Just adding tests? Use test-writer

Just verifying accuracy? Use fact-check

Just optimizing SEO? Use seo-review

Workflow Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                     COMPLETE CONCEPT WORKFLOW                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  INPUT: Concept name (e.g., "hoisting", "event-loop", "promises")           │
│                                                                              │
│  ┌──────────────────┐                                                        │
│  │ PHASE 1: RESEARCH │                                                       │
│  │ resource-curator  │  Find MDN refs, articles, videos                      │
│  └────────┬─────────┘                                                        │
│           ▼                                                                  │
│  ┌──────────────────┐                                                        │
│  │ PHASE 2: WRITE   │                                                        │
│  │ write-concept    │  Create the documentation page                         │
│  └────────┬─────────┘                                                        │
│           ▼                                                                  │
│  ┌──────────────────┐                                                        │
│  │ PHASE 3: TEST    │                                                        │
│  │ test-writer      │  Generate tests for all code examples                  │
│  └────────┬─────────┘                                                        │
│           ▼                                                                  │
│  ┌──────────────────┐                                                        │
│  │ PHASE 4: VERIFY  │                                                        │
│  │ fact-check       │  Verify accuracy, run tests, check links               │
│  └────────┬─────────┘                                                        │
│           ▼                                                                  │
│  ┌──────────────────┐                                                        │
│  │ PHASE 5: OPTIMIZE│                                                        │
│  │ seo-review       │  SEO audit and final optimizations                     │
│  └────────┬─────────┘                                                        │
│           ▼                                                                  │
│  OUTPUT: Complete, tested, verified, SEO-optimized concept page              │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Phase 1: Resource Curation

Skill: resource-curator
Goal: Gather high-quality external resources before writing

What to Do

Identify the concept category (fundamentals, async, OOP, etc.)

Search for MDN references — Official documentation

Find quality articles — Target 4-6 from trusted sources

Find quality videos — Target 3-4 from trusted creators

Evaluate each resource — Check quality criteria

Write specific descriptions — 2 sentences each

Format as Card components — Ready to paste into the page

Deliverables

List of 2-4 MDN/reference links with descriptions

List of 4-6 article links with descriptions

List of 3-4 video links with descriptions

Optional: 1-2 courses or books

Quality Gates

Before moving to Phase 2:

 All links verified working (200 response)

 All resources are JavaScript-focused

 Descriptions are specific, not generic

 Mix of beginner and advanced content

Phase 2: Concept Writing

Skill: write-concept
Goal: Create the full documentation page

What to Do

Determine the category for file organization

Create the frontmatter (title, sidebarTitle, description)

Write the opening hook — Question that draws readers in

Add opening code example — Simple example in first 200 words

Write "What you'll learn" box — 5-7 bullet points

Write main content sections:

What is [concept]? (with 40-60 word definition for featured snippet)

Real-world analogy

How it works (with diagrams)

Code examples (multiple, progressive complexity)

Common mistakes

Edge cases

Add Key Takeaways — 8-10 numbered points

Add Test Your Knowledge — 5-6 Q&A accordions

Add Related Concepts — 4 Cards linking to related topics

Add Resources — Paste resources from Phase 1

Deliverables

Complete .mdx file at /docs/concepts/{concept-name}.mdx

File added to docs.json navigation (if new)

Quality Gates

Before moving to Phase 3:

 Frontmatter complete (title, sidebarTitle, description)

 Opens with question hook

 Code example in first 200 words

 "What you'll learn" Info box present

 All required sections present

 Resources section complete

 1,500+ words

Phase 3: Test Writing

Skill: test-writer
Goal: Create comprehensive tests for all code examples

What to Do

Scan the concept page for all code examples

Categorize examples:

Testable (console.log, return values)

DOM-specific (needs jsdom)

Error examples (toThrow)

Conceptual (skip)

Create test file at tests/{category}/{concept}/{concept}.test.js

Create DOM test file (if needed) at tests/{category}/{concept}/{concept}.dom.test.js

Write tests for each code example with source line references

Run tests to verify all pass

Deliverables

Test file: tests/{category}/{concept-name}/{concept-name}.test.js

DOM test file (if applicable): tests/{category}/{concept-name}/{concept-name}.dom.test.js

All tests passing

Quality Gates

Before moving to Phase 4:

 All testable code examples have tests

 Source line references in comments

 Tests pass: npm test -- tests/{category}/{concept}/

 DOM tests in separate file with jsdom directive

Phase 4: Fact Checking

Skill: fact-check
Goal: Verify technical accuracy of all content

What to Do

Verify code examples:

Run tests: npm test -- tests/{category}/{concept}/

Check any untested examples manually

Verify output comments match actual outputs

Verify MDN/spec claims:

Click all MDN links — verify they work

Compare API descriptions to MDN

Check ECMAScript spec for nuanced claims

Verify external resources:

Check all article/video links work

Skim content for accuracy

Verify descriptions match content

Audit technical claims:

Look for "always/never" statements

Verify performance claims

Check for common misconceptions

Generate fact-check report

Deliverables

Fact-check report documenting:

Code verification results

Link check results

Any issues found and fixes made

Quality Gates

Before moving to Phase 5:

 All tests passing

 All MDN links valid

 All external resources accessible

 No technical inaccuracies found

 No common misconceptions

Phase 5: SEO Review

Skill: seo-review
Goal: Optimize for search visibility

What to Do

Audit title tag:

50-60 characters

Primary keyword in first half

Ends with "in JavaScript"

Contains compelling hook

Audit meta description:

150-160 characters

Starts with action word (Learn, Understand, Discover)

Contains primary keyword

Promises specific value

Audit keyword placement:

Keyword in title

Keyword in description

Keyword in first 100 words

Keyword in at least one H2

Audit content structure:

Question hook opening

Code in first 200 words

"What you'll learn" box

Short paragraphs

Audit featured snippet optimization:

40-60 word definition after "What is" H2

Question-format H2s

Numbered steps for how-to content

Audit internal linking:

3-5 related concepts linked

Descriptive anchor text

Related Concepts section complete

Calculate score and fix any issues

Deliverables

SEO audit report with score (X/27)

All high-priority fixes implemented

Quality Gates

Before marking complete:

 Score 24+ out of 27 (90%+)

 Title optimized

 Meta description optimized

 Keywords placed naturally

 Featured snippet optimized

 Internal links complete

Complete Workflow Checklist

Use this master checklist to track progress through all phases.

# Concept Workflow: [Concept Name]

**Started:** YYYY-MM-DD
**Target Category:** {category}
**File Path:** `/docs/concepts/{concept-name}.mdx`
**Test Path:** `/tests/{category}/{concept-name}/`

---

## Phase 1: Resource Curation
- [ ] MDN references found (2-4)
- [ ] Articles found (4-6)
- [ ] Videos found (3-4)
- [ ] All links verified working
- [ ] Descriptions written (specific, 2 sentences)
- [ ] Resources formatted as Cards

**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

## Phase 2: Concept Writing
- [ ] Frontmatter complete
- [ ] Opening hook written
- [ ] Opening code example added
- [ ] "What you'll learn" box added
- [ ] Main content sections written
- [ ] Key Takeaways added
- [ ] Test Your Knowledge added
- [ ] Related Concepts added
- [ ] Resources pasted from Phase 1
- [ ] Added to docs.json (if new)

**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

## Phase 3: Test Writing
- [ ] Code examples extracted and categorized
- [ ] Test file created
- [ ] DOM test file created (if needed)
- [ ] All testable examples have tests
- [ ] Source line references added
- [ ] Tests run and passing

**Test Results:** X passing, X failing

**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

## Phase 4: Fact Checking
- [ ] All tests passing
- [ ] Code examples verified accurate
- [ ] MDN links checked (X/X valid)
- [ ] External resources checked (X/X valid)
- [ ] Technical claims audited
- [ ] No misconceptions found
- [ ] Issues fixed

**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

## Phase 5: SEO Review
- [ ] Title tag optimized (50-60 chars)
- [ ] Meta description optimized (150-160 chars)
- [ ] Keywords placed correctly
- [ ] Content structure verified
- [ ] Featured snippet optimized
- [ ] Internal links complete

**SEO Score:** X/27 (X%)

**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

## Final Status

**All Phases Complete:** ⬜ No | ✅ Yes
**Ready to Publish:** ⬜ No | ✅ Yes
**Completed:** YYYY-MM-DD

Execution Instructions

When executing this workflow, follow these steps:

Step 1: Initialize

Starting concept workflow for: [CONCEPT NAME]

Category: [fundamentals/functions-execution/web-platform/etc.]
File: /docs/concepts/[concept-name].mdx
Tests: /tests/[category]/[concept-name]/

Step 2: Execute Each Phase

For each phase:

Announce the phase:

## Phase X: [Phase Name]
Using skill: [skill-name]

Load the skill to get detailed instructions

Execute the phase following the skill's methodology

Report completion:

Phase X complete:
- [Deliverable 1]
- [Deliverable 2]
- Quality gates: ✅ All passed

Move to next phase only after quality gates pass

Step 3: Final Report

After all phases complete:

# Workflow Complete: [Concept Name]

## Summary
- **Concept Page:** `/docs/concepts/[concept-name].mdx`
- **Test File:** `/tests/[category]/[concept-name]/[concept-name].test.js`
- **Word Count:** X,XXX words
- **Code Examples:** XX (XX tested)
- **Resources:** X MDN, X articles, X videos

## Quality Metrics
- **Tests:** XX passing
- **Fact Check:** ✅ All verified
- **SEO Score:** XX/27 (XX%)

## Files Created/Modified
1. `/docs/concepts/[concept-name].mdx` (created)
2. `/docs/docs.json` (updated navigation)
3. `/tests/[category]/[concept-name]/[concept-name].test.js` (created)

## Ready to Publish: ✅ Yes

Phase Dependencies

Some phases can be partially parallelized, but the general flow should be:

Phase 1 (Resources) ──┐
                      ├──► Phase 2 (Writing) ──► Phase 3 (Tests) ──┐
                      │                                             │
                      │         ┌───────────────────────────────────┘
                      │         ▼
                      └──► Phase 4 (Fact Check) ──► Phase 5 (SEO)

Phase 1 before Phase 2: Resources inform what to write

Phase 2 before Phase 3: Need content before writing tests

Phase 3 before Phase 4: Tests are part of fact-checking

Phase 4 before Phase 5: Fix accuracy issues before SEO polish

Skill Reference

Phase
Skill
Purpose

1
resource-curator
Find and evaluate external resources

2
write-concept
Write the documentation page

3
test-writer
Generate tests for code examples

4
fact-check
Verify technical accuracy

5
seo-review
Optimize for search visibility

Each skill has detailed instructions in its own SKILL.md file. Load the appropriate skill at each phase for comprehensive guidance.

Time Estimates

Phase
Estimated Time
Notes

Phase 1: Resources
15-30 min
Depends on availability of quality resources

Phase 2: Writing
1-3 hours
Depends on concept complexity

Phase 3: Tests
30-60 min
Depends on number of code examples

Phase 4: Fact Check
15-30 min
Most automated via tests

Phase 5: SEO
15-30 min
Mostly checklist verification

Total
2-5 hours
For a complete concept page

Quick Start

To start the workflow for a new concept:

1. Determine the concept name and category
2. Load this skill (concept-workflow)
3. Execute Phase 1: Load resource-curator, find resources
4. Execute Phase 2: Load write-concept, write the page
5. Execute Phase 3: Load test-writer, create tests
6. Execute Phase 4: Load fact-check, verify accuracy
7. Execute Phase 5: Load seo-review, optimize SEO
8. Generate final report
9. Commit changes

Example prompt to start:

"Create a complete concept page for 'hoisting' using the concept-workflow skill"

This will trigger the full end-to-end workflow, creating a complete, tested, verified, and SEO-optimized concept page.