blueprint-curate-docs

/blueprint:curate-docs

Curate library or project documentation into .claude/rules/ entries optimized for AI agents — concise, actionable, gotcha-aware context that is auto-loaded into sessions and referenceable from PRPs.

Note: earlier blueprint versions wrote these entries to docs/blueprint/ai_docs/. That location is deprecated — .claude/rules/ is the canonical home for curated AI context, since rules are loaded by Claude Code natively and shared with every contributor.

Usage: /blueprint:curate-docs [library-name] or /blueprint:curate-docs project:[pattern-name]

When to Use This Skill

Use this skill when...	Use alternative when...
Documenting library gotchas for PRP/context reuse	Reading raw documentation for ad-hoc tasks
Codifying project patterns as rules	One-time library usage
Building a knowledge base under .claude/rules/	General library research

Context

• Rules directory: !find . -maxdepth 2 -type d -name rules -path '*/.claude/*'
• Existing rules: !find . -maxdepth 3 -path '*/.claude/rules/*' -name "*.md" -type f
• Rules path override: !find . -maxdepth 3 -path '*/docs/blueprint/manifest.json' -exec jq -r '.structure.generated_rules_path // ".claude/rules/"' {} +
• Library in dependencies: !find . -maxdepth 1 \( -name package.json -o -name pyproject.toml -o -name requirements.txt \) -exec grep -m1 "^$1[\":@=]" {} +

Parameters

Parse $ARGUMENTS:

• library-name: Name of library to document (e.g., redis, pydantic)
  • Location: $RULES_DIR/lib-[library-name].md
  • OR project:[pattern-name] for project patterns
  • Location: $RULES_DIR/[pattern-name].md

$RULES_DIR is structure.generated_rules_path from docs/blueprint/manifest.json when set, otherwise .claude/rules/.

Execution

Execute complete documentation curation workflow:

Step 1: Determine target and check existing rules

1. Parse argument to determine if library or project pattern
2. Resolve $RULES_DIR (manifest structure.generated_rules_path, default .claude/rules/)
3. Check if a rule for this library/pattern already exists in $RULES_DIR
4. If exists → Ask: Update in place or skip?
5. Check project dependencies for library version

Step 2: Research and gather documentation

For libraries:

• Find official documentation URL
• Search for specific sections relevant to project use cases
• Find known issues and gotchas (WebSearch: "{library} common issues", "{library} gotchas")
• Extract key sections with WebFetch

For project patterns:

• Search codebase for pattern implementations: grep -r "{pattern}" src/
• Identify where and how it's used
• Document conventions and variations
• Extract real code examples from project

Step 3: Extract key information

1. Use cases: How/why this library/pattern is used in project
2. Common operations: Most frequent uses
3. Patterns we use: Project-specific implementations (with file references)
4. Configuration: How it's configured in this project
5. Gotchas: Version-specific behaviors, common mistakes, performance pitfalls, security considerations

Sources for gotchas: GitHub issues, Stack Overflow, team experience, official docs warnings.

Step 4: Create the rule entry

Generate the file at $RULES_DIR/lib-[library-name].md or $RULES_DIR/[pattern-name].md (see REFERENCE.md).

Never overwrite a hand-authored rule. If a file with the target name exists and was not produced by this skill, pick a distinct name (e.g. lib-[library-name]-gotchas.md) or ask.

Include all sections from template: Quick Reference, Patterns We Use, Configuration, Gotchas, Testing, Examples.

Keep under 200 lines total.

Step 5: Add code examples

Include copy-paste-ready code snippets from:

• Project codebase (reference actual files and line numbers)
• Official documentation examples
• Stack Overflow solutions
• Personal implementation experience

Step 6: Update task registry

Update the task registry entry in docs/blueprint/manifest.json:

jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --argjson processed "${ITEMS_PROCESSED:-0}" \
  --argjson created "${ITEMS_CREATED:-0}" \
  '.task_registry["curate-docs"].last_completed_at = $now |
   .task_registry["curate-docs"].last_result = "success" |
   .task_registry["curate-docs"].stats.runs_total = ((.task_registry["curate-docs"].stats.runs_total // 0) + 1) |
   .task_registry["curate-docs"].stats.items_processed = $processed |
   .task_registry["curate-docs"].stats.items_created = $created' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

Step 7: Validate and save

1. Verify entry is < 200 lines
2. Verify all code examples are accurate
3. Verify gotchas include solutions
4. Save file
5. Report completion, including the rule path so PRPs can reference it

Agentic Optimizations

Context	Command
Resolve rules dir	jq -r '.structure.generated_rules_path // ".claude/rules/"' docs/blueprint/manifest.json
List existing rules	ls .claude/rules/ 2>/dev/null
Check library version	grep "{library}" package.json pyproject.toml 2>/dev/null | head -1
Search for patterns	Use grep on src/ for project patterns
Fast research	Use WebSearch for common issues instead of fetching docs

---

For the rule template, section guidelines, and example entries, see REFERENCE.md.