Converting Docs to Skills
Converts technical documentation, agent frameworks, and workflow notes into structured SKILL.md specifications and Gemini Spark automations. Use when turning raw docs, chat history, or coursework notes into reusable agent skills, when building task-identifier prompts for multi-agent systems, or when packaging Rust microservice/MCP architecture patterns into skill format.
Given a source artifact (doc, chat log, framework spec), produce a SKILL.md:
Input: Rust microservice retry-handling notes + MCP tool-call schema
Output: SKILL.md with name "handling-microservice-retries", workflow steps
for backoff/circuit-breaking, and example MCP tool payloads
Default output is always a single skill file with YAML frontmatter, never a summary or explanation.
Progress:
- Step 1: Identify the core repeatable task in the source material (strip away narrative/history)
- Step 2: Name the skill in gerund-kebab-case
- Step 3: Write third-person description with explicit trigger phrases
- Step 4: Extract or infer a concrete Quick Start example
- Step 5: Break the methodology into ordered workflow steps (checklist if >4 steps)
- Step 6: Pull 2-3 concrete input/output examples from source material
- Step 7: List best practices actually evidenced in the source (not generic advice)
- Step 8: List pitfalls observed (e.g., vague descriptions, missing triggers, monolithic skills)
- Step 9: If source describes a multi-agent trigger system, add a "task-identifier" subsection mapping trigger phrases → agent/skill routing
- Step 10: Trim to ~500 lines; if longer, split into linked files (e.g.,
reference.md,examples.md)
Task-Identifier Sub-Workflow
When the source is about routing tasks across multiple agents/skills:
- Enumerate candidate agents/skills and their one-line purpose.
- For each, extract 3-5 trigger phrases from real usage (chat history, queries).
- Build a decision table:
trigger phrase pattern → skill name → confidence signal. - Flag ambiguous triggers that map to >1 skill; resolve by specificity (prefer the more specialized skill).
- Emit this table as a
task-identifier.mdreference file alongside the SKILL.md, not inline in frontmatter.
Example 1: Input: A month of chat history showing repeated searches for "SKILL.md spec", "Gemini Spark automation", "MCP tool schema" Output:
YAML--- name: building-gemini-spark-workflows description: Builds automated Gemini Spark workflows from architecture notes and prompt requests. Use when converting saved Sparks into executable automation chains or when drafting new Spark prompt templates. ---
Plus Quick Start showing a Spark trigger → action → output chain.
Example 2:
Input: "Build task-identifier skill prompt" + "Explore multi-agent workflow triggers"
Output: A routing-agent-tasks skill whose Quick Start shows a raw user request being matched against a trigger table and routed to the correct downstream skill, with the task-identifier sub-workflow table included as a linked reference file.
Example 3:
Input: Gmail coursework snippets on Rust microservices + MCP architecture
Output: A documenting-mcp-tool-contracts skill capturing how to translate a Rust service's tool schema into an MCP-compliant SKILL.md, with examples of request/response JSON.
- Mine actual chat/search history for trigger phrases instead of inventing generic ones — real queries make better
descriptionfields. - Keep one skill = one repeatable task; split "SKILL.md builder" from "Spark workflow builder" from "task router" rather than merging them.
- When multiple related skills emerge (as here), also produce a short index noting how they relate (e.g., router → calls → specific skill).
- Preserve architecture-template language (Rust, MCP) verbatim in examples so the skill stays technically grounded.
- Date-stamp nothing in the skill body itself — skills should be timeless artifacts, not snapshots of "yesterday's" work.
- Don't leave
descriptionvague ("helps with skills") — it must name concrete triggers like "when converting chat history into SKILL.md". - Don't bundle the task-identifier/router logic into every skill's frontmatter; keep it in a dedicated routing skill or reference file.
- Don't narrate the user's activity history inside the skill file — extract the pattern, discard the anecdote.
- Don't let multi-agent trigger tables balloon the main SKILL.md past ~500 lines; externalize them.