OpenSkillIndex← back to search
claude-code

Claude-project-skills-template docs-refresh

name: docs-refresh

install
source · Clone the upstream repo
git clone https://github.com/dohernandez/claude-project-skills-template
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/dohernandez/claude-project-skills-template "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/docs-refresh" ~/.claude/skills/dohernandez-claude-project-skills-template-docs-refresh-969e87 && rm -rf "$T"
manifest: .claude/skills/docs-refresh/skill.yaml
source content

name: docs-refresh kind: gate version: "2.0.0" description: "Auto-generate skill reference docs and keep CLAUDE.md skills table in sync." severity: high tags:

  • documentation
  • skills
  • repo-hygiene
  • generation

purpose: | Auto-generate docs/skills/REFERENCE.md from skill.yaml files and keep the CLAUDE.md skills table in sync between HTML marker comments.

Pipeline:

  1. generate-skill-reference.sh -> docs/skills/REFERENCE.md
  2. update-claude-md.sh -> CLAUDE.md (between SKILLS_TABLE markers)
  3. docs-refresh-check.sh -> verifies sync (CI gate)

owns:

  • "docs/skills/REFERENCE.md generation"
  • "CLAUDE.md skills table (between SKILLS_TABLE markers)"
  • "Documentation sync between skill.yaml files and generated docs"

permissions:

  • "You MUST run 'task docs:refresh' after adding/removing/modifying skills"
  • "You MUST NOT hand-edit docs/skills/REFERENCE.md"
  • "You MUST NOT hand-edit content between SKILLS_TABLE markers in CLAUDE.md"

entry_points:

  • command: "task docs:refresh" description: "Generate REFERENCE.md and update CLAUDE.md table"
  • command: "task docs:refresh-check" description: "Verify generated docs are in sync"
  • command: "task claude:skills-reference" description: "Generate REFERENCE.md only"

documentation_sources: skill_reference: description: "Auto-generated skill reference document" sources: - path: ".claude/skills//skill.yaml" extracts: "name, kind, description, version, severity, tags, purpose, owns, anti_patterns" - path: ".claude/skills//sharp-edges.yaml" extracts: "edge id, description" - path: ".claude/skills/*/SKILL.md" extracts: "user-invocable frontmatter field" output: file: "docs/skills/REFERENCE.md" generator: "task claude:skills-reference" update_trigger: "When any skill.yaml, sharp-edges.yaml, or SKILL.md frontmatter changes"

claude_md_table: description: "Skills table in CLAUDE.md between HTML markers" sources: - path: ".claude/skills//skill.yaml" extracts: "name, kind, description" - path: ".claude/skills//SKILL.md" extracts: "user-invocable frontmatter field" output: file: "CLAUDE.md" generator: "task docs:refresh (update-claude-md.sh)" section: "Between <!-- SKILLS_TABLE_START --> and <!-- SKILLS_TABLE_END -->" update_trigger: "When skills are added, removed, or descriptions change"

patterns:

  • id: run-refresh-after-changes description: "Always run 'task docs:refresh' after skill changes, not manual edits" example: |

    1. Create/modify/delete a skill
    2. Run: task docs:refresh
    3. Verify: task docs:refresh-check
    4. Commit generated files with source changes

  • id: never-hand-edit-generated description: "Never hand-edit REFERENCE.md or content between CLAUDE.md markers" example: |

    Wrong: directly editing docs/skills/REFERENCE.md

    Right: modify skill.yaml, then run task docs:refresh

  • id: commit-generated-with-source description: "Always commit generated docs in the same commit as source changes"

anti_patterns:

  • id: stale-reference description: "REFERENCE.md doesn't match current skill.yaml files" why_bad: "Outdated reference document misleads Claude and developers"

  • id: hand-edited-generated description: "Manually editing REFERENCE.md or content between CLAUDE.md markers" why_bad: "Changes will be overwritten on next task docs:refresh run"

  • id: skip-after-skill-change description: "Creating or removing a skill without running task docs:refresh" why_bad: "Generated docs become stale. Refresh-check will fail."

  • id: missing-markers description: "CLAUDE.md missing SKILLS_TABLE_START/END markers" why_bad: "update-claude-md.sh cannot update the skills table"

procedure:

  • step: "Run the refresh pipeline" detail: "Execute task docs:refresh to regenerate all docs" commands:

    • "task docs:refresh"

  • step: "Verify sync" detail: "Run the check to confirm everything is in sync" commands:

    • "task docs:refresh-check"

  • step: "Review changes" detail: "Check git diff on REFERENCE.md and CLAUDE.md for correctness" commands:

    • "git diff docs/skills/REFERENCE.md"
    • "git diff CLAUDE.md"

  • step: "Commit together" detail: "Commit generated docs alongside the skill changes that triggered them"