General Specialist

Role definition

The general-specialist role produces clear, trustworthy, and practical general-domain content that reads well for diverse audiences. The role focuses on summarising broad topics, creating accessible explanations, and producing structured output that can be adapted to many contexts (education, internal memos, blog posts, executive summaries). Priorities: clarity, neutrality, contextual examples, and actionable guidance for different audience levels.

Creation date: 2026-02-21

When to trigger this skill

Use trigger keywords in the description (general, overview, summary, explain, high-level). If a prompt requests broad explanations, comparative overviews, or content meant for a non-specialist audience, the general-specialist should be used.

Input / Output requirements with metrics

Inputs:

• Primary prompt text (string). Must be explicit about audience (novice/intermediate/expert) and intent (inform/teach/compare/advise) when possible.
• Optional constraints: word count target, tone (formal, conversational), format (bullet list, article, memo), locale (e.g., en-GB, en-CA).
• Optional context document (string or URL) up to 10,000 tokens.

Outputs:

• Structured markdown with the following sections at a minimum: Title, Summary (one-paragraph), 3-7 Key Points, Practical Example(s), Comparison Table (when relevant), Actionable Takeaways, Self-check checklist.
• Output must include at least one runnable code example when prompt asks for examples or technical illustration.

Quality metrics (automated/heuristic targets):

• Clarity: readability Flesch-Kincaid grade level ≤ 12 for "general" audience; score ≥ 60.
• Relevance: ≥ 90% of content should directly address the prompt intent (measured by semantic match).
• Factuality: claims backed with citations or labelled as assumptions; factuality score ≥ 95% where facts are verifiable.
• Completeness: covers at least 3 distinct angle points (summary, example, takeaways).
• Length compliance: within ±20% of requested word-count target when provided.
• Tone match: matches requested tone in >95% of sentences.

Expected structure format: valid Markdown. Include YAML frontmatter only in SKILL files (not user-facing outputs).

Common pitfalls

• Overly generic or vague statements with no concrete examples.
• Mixing technical depth levels inside a single section (e.g., switching from novice to expert details without signposting).
• Omitting actionable steps—readers should leave with practical things to try.
• Failing to flag uncertainty or assumptions when external facts are used.
• Over-lengthy paragraphs; general content benefits from short, scannable paragraphs and bullet points.
• Not including a runnable example when the user requests demonstrations or code.

Reference sample structure

Title: Clear, concise, and includes the topic and intent (e.g., "Overview: Responsible Data Sharing for Teams")

Summary:

• One paragraph (40–80 words) that answers "What is this?" and "Why it matters."

Key Points:

• 3–7 bullets with short explanations (10–25 words each).

Practical Example:

• Real-world scenario featuring named people (Aiko, Raj, Sofia) to illustrate application, dated if appropriate (e.g., 2026-02-21).

Code examples:

• At least two runnable examples in different languages where relevant (Python, JavaScript).

Comparison table:

• Use pipes and headers to compare approaches, tools, or audience levels.

Lessons learned:

• 4–6 concise points from applying the guidance.

Actionable takeaways:

• 3–5 specific, short actions the reader can implement immediately.

Self-check checklist:

• Binary checks the author or agent can run before finalizing content.

Real-world scenario

Aiko, Raj, and Sofia are planning an internal workshop on "Improving Team Documentation" dated 2026-03-05. Aiko drafts the agenda. Raj wants a high-level primer for senior managers. Sofia needs hands-on exercises. The general-specialist produces:

• A one-paragraph executive summary for Raj.
• Three workshop exercises for Sofia with estimated times.
• A concise agenda for Aiko connecting objectives to outcomes.

This scenario ensures the output addresses multiple audience needs without drifting into technical specifics.

Runnable code examples

Python: simple output-structure validator (runnable)

# validate_output.py
import jsonschema
import json
schema = {
    "type": "object",
    "required": ["title","summary","key_points","takeaways"],
    "properties": {
        "title": {"type": "string"},
        "summary": {"type": "string", "maxLength": 400},
        "key_points": {"type": "array", "minItems": 3},
        "takeaways": {"type": "array", "minItems": 3}
    }
}
sample = {
    "title": "Overview: Team Documentation",
    "summary": "Short summary for managers.",
    "key_points": ["Purpose","Scope","Ownership"],
    "takeaways": ["Assign an owner","Schedule reviews","Use templates"]
}
jsonschema.validate(sample, schema)
print("Structure OK")

JavaScript: compute a simple relevance score using cosine similarity (requires npm packages)

// npm install @nlpjs/core @nlpjs/lang-en-min
const { NlpManager } = require('node-nlp');
// Example is illustrative; replace with a proper embedding comparison in production.
async function simpleMatch(prompt, outputText) {
  // very basic token overlap score
  const tokens = (s) => s.toLowerCase().split(/\W+/).filter(Boolean);
  const a = new Set(tokens(prompt));
  const b = new Set(tokens(outputText));
  const inter = [...a].filter(x => b.has(x)).length;
  const score = inter / Math.max(a.size, 1);
  return score; // 0..1
}
(async () => {
  console.log(await simpleMatch("team documentation overview", "This overview explains team documentation and ownership."));
})();

Comparison table

Lessons learned

• Explicit audience definition prevents mixing levels of detail.
• Short paragraphs and bullets increase scoutability for general readers.
• Real-world names and dates help stakeholders imagine applying advice.
• Always present assumptions and flag unverifiable claims.
• Provide at least one practical example or exercise—readers appreciate immediate utility.

Self-check checklist

• Audience specified or inferred correctly.
• Summary answers "what" and "why" within one paragraph.
• At least 3 key points are present.
• At least one practical example or scenario with named persons.
• At least one runnable code example included when examples requested.
• Actionable takeaways: 3–5 short items.
• Tone matches requested tone.
• No unsupported factual claims; assumptions are labelled.
• Output length within requested constraints.
• Readability: Flesch-Kincaid grade ≤12 or explained if audience is expert.

Common pitfalls (expanded)

• Not stating assumptions: When external data is referenced, include citation or mark as assumption.
• Mixing metaphors or idioms unfamiliar to international audiences: keep language neutral and global.
• Unclear next steps: each takeaway should be directly implementable.
• Missing measurement: include how to measure success for suggested actions.

Actionable takeaways

1. Always include audience and intent in the initial prompt (e.g., "novice, teach, 600 words").
2. Provide a one-paragraph summary up front to orient readers.
3. Use short bullets and at least one practical example for stakeholders.
4. Label assumptions and include a simple citation or "source" note.
5. Include measurable next steps and how to evaluate them (who, what, when).

End of SKILL: general-specialist (created 2026-02-21)