Turn Project Docs into Agent Skills and Keep Them Up to Date

## Check Who Maintains a Skill Before You Edit It Determine how each skill is owned before creating or updating files. Use generated skills for projects that publish documentation but do not maintain an agent-skill package, synchronized skills for projects that already publish their own skills, and hand-written skills for intentionally curated expertise. Do not mix these workflows. Generated skills are synthesized from documentation, synchronized skills are copied from their upstream skill source, and hand-written skills remain untouched unless the task explicitly includes them. ## Keep Only the Docs Content That Helps the Agent Do Tasks Focus on capabilities, decision points, practical usage patterns, working examples, and the circumstances in which an agent should choose one approach over another. Prefer knowledge that materially improves task execution. Skip user-facing introductions, installation walkthroughs, generic getting-started material, promotional prose, and concepts a capable model already handles reliably. Rewrite and synthesize source material instead of copying documentation verbatim. Keep the skill compact. Create only the references needed to cover distinct concepts, avoid redundant files, and explain both how a pattern works and why or when it should be used. ## Register a New Project and Generate Its Skill Add a new generated source to the repository's authoritative project registry, including its source location and stable project identifier. Initialize or synchronize the source through the supported repository workflow rather than creating an untracked local copy. Read the project's documentation and any project-specific generation instructions completely enough to understand its capabilities and conventions. Organize the useful material into categories such as core concepts, features, best practices, and advanced workflows. Create the output directory whose name matches the registered generated-source identifier. Write the reference files, build the skill index, and record generation metadata containing the exact source revision. ## Update Generated Skills Only Where the Docs Changed Read the source revision recorded in the generation metadata and compare it with the current source. Limit the source diff to the documentation area that governs the generated skill. Update only references affected by that diff, then refresh the index's project version, generation date, topic table, and descriptions where necessary. Preserve unaffected references and avoid regenerating unrelated content merely because the source repository advanced. After review, replace the recorded revision with the exact revision used for the update so the next comparison has a trustworthy baseline. ## Copy Upstream-Maintained Skills Without Editing Them by Hand For an upstream-maintained skill, use the registry to determine which source skill to copy and which output name to use. The output name may intentionally differ from the upstream directory, so never infer it from the source name alone. On first import, copy the configured skill tree and record the upstream revision in synchronization metadata. For updates, compare the recorded revision with the current upstream skill directory, copy only the configured changed files, and advance the recorded revision. Never modify synchronized skill content manually. Contribute corrections to the upstream owner and bring them back through the synchronization workflow so local copies do not drift. ## Write a Short Skill Index That Links to Each Reference Give the skill index valid frontmatter with a kebab-case name, a concise capability description, provenance metadata, the generation or synchronization date, and the relevant tool or project version. Add a short orientation paragraph, then group references into clear categories. For each topic, provide a brief description and a relative link to the corresponding reference so an agent can load only the material needed for the current task. Keep the index concise and navigational. Do not duplicate full reference content in the index or add entries for files that do not exist. ## Cover One Practical Topic in Each Reference File Give every reference file frontmatter with a stable name and focused description, followed by a clear concept title. Cover one coherent capability or workflow per file rather than combining unrelated features. Include practical usage guidance, working code examples when the concept is executable, key constraints, and the reasoning behind recommended patterns. Remove background that does not help an agent make or execute a decision. End with source references that identify the documentation used to synthesize the content. Keep those references traceable without turning the skill into a copy of the source material. ## Record the Source Revision and Date Behind Each Skill For generated skills, record the source location, exact source revision, and generation date. For synchronized skills, record the upstream skill location, exact upstream revision, and synchronization date. Keep the index version aligned with the actual source state and use the last generation or synchronization date according to repository policy. Do not claim a newer project version or revision than the content was derived from. Treat the registry as the canonical list of supported projects and source locations. Avoid duplicating mutable repository URLs or ownership mappings across skill files when the registry already owns them. ## Check the Final Diff for Broken Links and Stale Revisions Before completion, confirm the source classification, registry entry, output naming rule, index links, reference frontmatter, category organization, revision metadata, and source citations all agree. Verify that generated content is synthesized rather than copied, synchronized content has no manual drift, hand-written skills were not touched without scope, and every reference contributes distinct agent value. Review the final diff for unrelated files, excessive references, stale versions, missing examples, broken links, and unrecorded source changes. Report any source or tooling limitation that prevented a complete generation or synchronization.