| name | concept-workflow |
| description | End-to-end workflow for creating complete JavaScript concept documentation, orchestrating all skills from research to final review |
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
.mdxfile at/docs/concepts/{concept-name}.mdx - File added to
docs.jsonnavigation (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
- Run tests:
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 passedMove 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.