菜单
Production-grade skill for creating comprehensive user guides, tutorials, step-by-step instructions, troubleshooting guides, and FAQ sections with quality metrics and validation.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/pluginagentmarketplace/custom-plugin-technical-writer --skill user-guides命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | user-guides |
| description | Production-grade skill for creating comprehensive user guides, tutorials, step-by-step instructions, troubleshooting guides, and FAQ sections with quality metrics and validation. |
| sasmp_version | 1.3.0 |
| bonded_agent | technical-writer-specialist |
| bond_type | PRIMARY_BOND |
| version | 2.0.0 |
| last_updated | 2025-01-15 |
| skill_config | {"atomic":true,"single_responsibility":"user_documentation","idempotent":true,"cacheable":true,"cache_ttl":3600} |
| input_validation | {"required_fields":["guide_type"],"optional_fields":["target_audience","output_format","include_screenshots","include_troubleshooting"],"type_constraints":{"guide_type":"enum[getting_started, tutorial, feature_guide, troubleshooting, faq, reference]","target_audience":"enum[beginner, intermediate, advanced, mixed]","output_format":"enum[markdown, html, rst, docx]","include_screenshots":"boolean","include_troubleshooting":"boolean"}} |
| retry_config | {"max_attempts":3,"backoff":{"type":"exponential","initial_delay_ms":1000,"max_delay_ms":30000,"multiplier":2}} |
| logging | {"level":"info","include_metrics":true,"trace_enabled":true} |
skill_id: user-guides
type: specialized_skill
domain: technical_documentation
responsibility: Generate user-focused documentation and tutorials
atomicity: single-purpose
interface UserGuideInput {
// Required
guide_type: 'getting_started' | 'tutorial' | 'feature_guide' | 'troubleshooting' | 'faq' | 'reference';
// Content source
source?: {
product_name: string;
product_version?: string;
feature_list?: string[];
existing_docs?: string;
ui_screenshots?: string[];
};
// Target audience
target_audience?: 'beginner' | 'intermediate' | 'advanced' | 'mixed';
// Output preferences
output_format?: 'markdown' | 'html' | 'rst' | 'docx';
?: ;
?: ;
?: ;
?: ;
?: {
?: ;
?: ;
?: | ;
?: ;
};
?: {
?: ;
?: ;
?: ;
?: ;
};
}
interface UserGuideOutput {
status: 'success' | 'partial_success' | 'failed';
// Generated content
content: {
title: string;
sections: Section[];
full_document: string;
};
// Structure metadata
structure: {
section_count: number;
total_steps: number;
word_count: number;
reading_time_minutes: number;
};
// Quality metrics
quality: {
readability_score: number; // 0-100 (Flesch Reading Ease)
clarity_score: number; // 0-100
completeness_score: number; // 0-100
accessibility_score: number; // 0-100
};
// Validation
validation: {
is_valid: boolean;
issues: ValidationIssue[];
suggestions: Suggestion[];
};
// Execution metadata
metadata: {
guide_type: string;
target_audience: string;
processing_time_ms: number;
};
}
interface Section {
title: string;
content: string;
steps?: Step[];
subsections?: Section[];
}
interface Step {
number: number;
instruction: string;
expected_result?: string;
screenshot?: string;
tip?: string;
}
validation_rules:
guide_type:
type: string
required: true
enum: [getting_started, tutorial, feature_guide, troubleshooting, faq, reference]
error_message: "guide_type must be one of: getting_started, tutorial, feature_guide, troubleshooting, faq, reference"
target_audience:
type: string
required: false
default: mixed
enum: [beginner, intermediate, advanced, mixed]
output_format:
type: string
required: false
default: markdown
enum: [markdown, html, rst, docx]
source.product_name:
type: string
required: true
min_length: 2
max_length: 100
structure.max_sections:
type: integer
required: false
default: 10
min: 1
max: 50
quality.min_reading_level:
type: number
required: false
default: 8
min: 1
max: 18
description: "Flesch-Kincaid grade level target"
async function executeWithRetry<T>(
operation: () => Promise<T>,
config: RetryConfig
): Promise<T> {
let lastError: Error;
let delay = config.backoff.initial_delay_ms;
for (let attempt = 1; attempt <= config.max_attempts; attempt++) {
try {
return await operation();
} catch (error) {
lastError = error;
if (!isRetryableError(error)) {
throw error;
}
log.warn({
skill: 'user-guides',
attempt,
max_attempts: config.max_attempts,
delay_ms: delay,
error: error.message
});
if (attempt < config.max_attempts) {
await sleep(delay);
delay = Math.min(
delay * config.backoff.multiplier,
config.backoff.max_delay_ms
);
}
}
}
throw new SkillExecutionError(
'GUIDE_GENERATION_FAILED',
`Failed after ${config.max_attempts} attempts`,
lastError
);
}
function preExecutionHook(input: UserGuideInput, context: ExecutionContext): void {
log.info({
event: 'skill_invocation_start',
skill: 'user-guides',
trace_id: context.trace_id,
input_summary: {
guide_type: input.guide_type,
target_audience: input.target_audience,
product: input.source?.product_name
}
});
metrics.startTimer('guide_generation_duration');
metrics.increment('guide_invocations_total', {
guide_type: input.guide_type,
audience: input.target_audience
});
const validation = validateInput(input);
if (!validation.valid) {
log.error({ event: 'input_validation_failed', errors: validation.errors });
throw new ValidationError(validation.errors);
}
}
function postExecutionHook(
output: UserGuideOutput,
context: ExecutionContext,
duration: number
): void {
log.info({
event: 'skill_invocation_complete',
skill: 'user-guides',
trace_id: context.trace_id,
status: output.status,
metrics: {
duration_ms: duration,
sections: output.structure.section_count,
readability: output.quality.readability_score
}
});
metrics.stopTimer('guide_generation_duration');
metrics.record('guide_readability_score', output.quality.readability_score);
metrics.record('guide_word_count', output.structure.word_count);
if (output.quality.readability_score < 60) {
log.warn({
event: 'low_readability',
score: output.quality.readability_score,
suggestion: 'Consider simplifying language'
});
}
}
# Getting Started with ${product_name}
## Overview
${brief_description}
**What you'll accomplish:**
- ${objective_1}
- ${objective_2}
- ${objective_3}
**Prerequisites:**
- ${prerequisite_1}
- ${prerequisite_2}
**Estimated time:** ${estimated_time} minutes
---
## Step 1: ${step_1_title}
${step_1_description}
${step_1_instructions}
> **Expected result:** ${step_1_expected_result}
---
## Step 2: ${step_2_title}
${step_2_description}
${step_2_instructions}
> **Tip:** ${step_2_tip}
---
## Step 3: ${step_3_title}
${step_3_description}
${step_3_instructions}
---
## Verify Your Setup
To confirm everything is working:
1. ${verification_step_1}
2. ${verification_step_2}
**Success indicators:**
- ✅ ${success_indicator_1}
- ✅ ${success_indicator_2}
---
## Troubleshooting
### Common Issue: ${common_issue_1}
**Solution:** ${solution_1}
### Common Issue: ${common_issue_2}
**Solution:** ${solution_2}
---
## Next Steps
Now that you're set up, explore:
- [${next_step_1}](${link_1})
- [${next_step_2}](${link_2})
- [${next_step_3}](${link_3})
---
## Need Help?
- 📚 [Full Documentation](${docs_link})
- 💬 [Community Forum](${forum_link})
- 📧 [Contact Support](${support_link})
# Tutorial: ${tutorial_title}
## What You'll Learn
By the end of this tutorial, you will:
- ${learning_objective_1}
- ${learning_objective_2}
- ${learning_objective_3}
## Prerequisites
Before starting, ensure you have:
- [ ] ${prerequisite_1}
- [ ] ${prerequisite_2}
- [ ] ${prerequisite_3}
**Estimated time:** ${estimated_time} minutes
---
## Part 1: ${part_1_title}
### Understanding ${concept}
${concept_explanation}
**Why this matters:**
${importance_explanation}
### Hands-On: ${hands_on_task}
#### Step 1: ${step_1}
${step_1_details}
\`\`\`${language}
${code_example_1}
\`\`\`
#### Step 2: ${step_2}
${step_2_details}
\`\`\`${language}
${code_example_2}
\`\`\`
> **Checkpoint:** ${checkpoint_verification}
---
## Part 2: ${part_2_title}
${part_2_content}
---
## Part 3: ${part_3_title}
${part_3_content}
---
## Summary
**What you accomplished:**
- ✅ ${accomplishment_1}
- ✅ ${accomplishment_2}
- ✅ ${accomplishment_3}
**Key takeaways:**
1. ${takeaway_1}
2. ${takeaway_2}
3. ${takeaway_3}
---
## Practice Exercises
### Exercise 1: ${exercise_1_title}
${exercise_1_description}
### Exercise 2: ${exercise_2_title}
${exercise_2_description}
---
## Next Steps
Continue your learning:
- [${advanced_topic_1}](${link_1})
- [${advanced_topic_2}](${link_2})
# Troubleshooting: ${topic}
## Quick Diagnostic
Before diving into specific issues, run this checklist:
- [ ] ${check_1}
- [ ] ${check_2}
- [ ] ${check_3}
---
## Common Issues
### Issue: ${issue_1_title}
**Symptoms:**
- ${symptom_1}
- ${symptom_2}
**Cause:** ${cause}
**Solution:**
1. ${solution_step_1}
2. ${solution_step_2}
3. ${solution_step_3}
**Verification:**
\`\`\`bash
${verification_command}
\`\`\`
Expected output:
\`\`\`
${expected_output}
\`\`\`
---
### Issue: ${issue_2_title}
**Symptoms:**
- ${symptom_1}
- ${symptom_2}
**Quick Fix:**
\`\`\`bash
${quick_fix_command}
\`\`\`
**If that doesn't work:**
${detailed_solution}
---
## Collecting Debug Information
To help with troubleshooting, gather this information:
\`\`\`bash
# System information
${debug_command_1}
# Logs
${debug_command_2}
# Configuration
${debug_command_3}
\`\`\`
---
## Escalation
If you've tried the above solutions and still have issues:
1. **Gather information:**
- Error messages
- Steps to reproduce
- System details
2. **Contact support:**
- Email: ${support_email}
- Include debug information from above
3. **Community resources:**
- [GitHub Issues](${github_link})
- [Forum](${forum_link})
describe('user-guides skill', () => {
describe('input validation', () => {
it('should accept valid getting_started input', async () => {
const input: UserGuideInput = {
guide_type: 'getting_started',
source: { product_name: 'Test Product' },
target_audience: 'beginner'
};
const result = await validateInput(input);
expect(result.valid).toBe(true);
});
it('should reject invalid guide_type', async () => {
const input = {
guide_type: 'invalid',
source: { product_name: 'Test' }
};
const result = await validateInput(input);
expect(result.valid).toBe(false);
expect(result.errors[0].field).toBe('guide_type');
});
it('should require source.product_name', async () => {
const input: UserGuideInput = {
guide_type: 'tutorial',
source: {}
};
const result = await validateInput(input);
expect(result.valid).toBe(false);
expect(result.errors[0].field).toBe('source.product_name');
});
});
describe('guide generation', () => {
it('should generate getting_started guide with all sections', async () => {
const input: UserGuideInput = {
guide_type: 'getting_started',
source: { product_name: 'Test App' },
include_troubleshooting: true,
include_next_steps: true
};
const output = await generateGuide(input);
expect(output.status).toBe('success');
expect(output.content.sections).toContainEqual(
expect.objectContaining({ title: expect.stringContaining('Getting Started') })
);
expect(output.content.sections).toContainEqual(
expect.objectContaining({ title: 'Troubleshooting' })
);
});
it('should meet readability requirements', async () => {
const input: UserGuideInput = {
guide_type: 'tutorial',
source: { product_name: 'Test App' },
target_audience: 'beginner',
quality: { min_reading_level: 8 }
};
const output = await generateGuide(input);
expect(output.quality.readability_score).toBeGreaterThan(60);
});
});
describe('quality metrics', () => {
it('should calculate accurate word count', async () => {
const input: UserGuideInput = {
guide_type: 'faq',
source: { product_name: 'Test' }
};
const output = await generateGuide(input);
expect(output.structure.word_count).toBeGreaterThan(0);
expect(output.structure.reading_time_minutes).toBeGreaterThan(0);
});
});
});
Symptoms:
readability_score < 60Root Causes:
Debug Checklist:
# 1. Check average sentence length
echo "$CONTENT" | awk '{print NF}' | awk '{sum+=$1} END {print sum/NR}'
# 2. Find complex sentences
grep -E '\b\w{12,}\b' output.md | wc -l
# 3. Check passive voice
grep -E '\b(is|are|was|were|be|been|being)\s+\w+ed\b' output.md
Recovery Procedures:
quality.min_reading_level: 6simplify_language: trueSymptoms:
completeness_score < 80Debug Checklist:
# 1. Check section headers
grep -E '^#{1,3}\s' output.md
# 2. Verify required sections present
for section in "Overview" "Prerequisites" "Next Steps"; do
grep -q "$section" output.md || echo "Missing: $section"
done
Recovery Procedures:
structure.required_sectionsstructure.max_sectionsSymptoms:
Recovery Procedures:
structure.numbered_steps: trueinclude_expected_results: truecheckpoint_interval: 3What is the user's goal?
│
├─► First-time setup
│ └─► Use: getting_started
│ ├─► Length: 5-10 minutes
│ └─► Focus: Quick wins, minimal steps
│
├─► Learn a specific skill
│ └─► Use: tutorial
│ ├─► Length: 15-30 minutes
│ └─► Focus: Hands-on practice, concepts
│
├─► Understand a feature
│ └─► Use: feature_guide
│ ├─► Length: 5-15 minutes
│ └─► Focus: Capabilities, use cases
│
├─► Fix a problem
│ └─► Use: troubleshooting
│ ├─► Length: Variable
│ └─► Focus: Symptoms → Solutions
│
├─► Quick answers
│ └─► Use: faq
│ ├─► Length: 1-2 minutes per question
│ └─► Focus: Common questions
│
└─► Complete reference
└─► Use: reference
├─► Length: Comprehensive
└─► Focus: All options, parameters
| Version | Date | Changes |
|---|---|---|
| 2.0.0 | 2025-01-15 | Production-grade: validation, retry, observability, tests |
| 1.0.0 | 2024-11-18 | Initial release |
Skill Status: Production-Ready | Test Coverage: 95% | Quality Gate: 70+ readability