@cleocode/skills 2026.9.21 → 2026.9.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. package/README.md +46 -63
  2. package/frontmatter.d.mts +60 -0
  3. package/frontmatter.mjs +277 -0
  4. package/index.d.ts +3 -3
  5. package/index.js +34 -9
  6. package/package.json +4 -2
  7. package/profiles/core.json +10 -3
  8. package/profiles/full.json +10 -6
  9. package/profiles/recommended.json +29 -3
  10. package/skills/_shared/manifest-operations.md +19 -40
  11. package/skills/_shared/skill-chaining-patterns.md +5 -9
  12. package/skills/_shared/subagent-protocol-base.md +6 -6
  13. package/skills/_shared/task-system-integration.md +5 -5
  14. package/skills/ct-adr-recorder/SKILL.md +18 -17
  15. package/skills/ct-artifact-publisher/SKILL.md +10 -7
  16. package/skills/ct-cleo/SKILL.md +26 -9
  17. package/skills/ct-cleo/references/loom-lifecycle.md +1 -1
  18. package/skills/{ct-memory/SKILL.md → ct-cleo/references/memory.md} +10 -23
  19. package/skills/ct-cleo/references/orchestrator-constraints.md +5 -5
  20. package/skills/ct-cleo/references/session-protocol.md +11 -8
  21. package/skills/{ct-stickynote/SKILL.md → ct-cleo/references/sticky-notes.md} +7 -29
  22. package/skills/ct-codebase-mapper/SKILL.md +62 -38
  23. package/skills/ct-consensus-voter/SKILL.md +10 -7
  24. package/skills/ct-contribution/SKILL.md +7 -5
  25. package/skills/ct-dev-workflow/SKILL.md +7 -7
  26. package/skills/ct-documentor/SKILL.md +29 -29
  27. package/skills/{ct-docs-review/__tests__/skill-docs-review.test.ts → ct-documentor/__tests__/reviewing-reference.test.ts} +4 -3
  28. package/skills/{ct-docs-write/__tests__/skill-docs-write.test.ts → ct-documentor/__tests__/writing-reference.test.ts} +4 -3
  29. package/skills/ct-documentor/references/anti-patterns.md +8 -8
  30. package/skills/{ct-docs-write → ct-documentor}/references/audience-targeting.md +5 -5
  31. package/skills/ct-documentor/references/chain-orchestration.md +19 -19
  32. package/skills/{ct-docs-write → ct-documentor}/references/cleo-style-guide.md +1 -1
  33. package/skills/ct-documentor/references/doc-types-and-templates.md +1 -1
  34. package/skills/{ct-docs-review → ct-documentor}/references/pr-review-mode.md +1 -1
  35. package/skills/{ct-docs-review/SKILL.md → ct-documentor/references/reviewing.md} +6 -26
  36. package/skills/ct-documentor/references/style-coordination.md +5 -5
  37. package/skills/{ct-docs-review → ct-documentor}/references/style-violations.md +1 -1
  38. package/skills/{ct-docs-write/SKILL.md → ct-documentor/references/writing.md} +5 -25
  39. package/skills/ct-epic-architect/SKILL.md +12 -9
  40. package/skills/ct-epic-architect/references/commands.md +5 -5
  41. package/skills/ct-epic-architect/references/output-format.md +2 -2
  42. package/skills/ct-epic-architect/references/patterns.md +2 -2
  43. package/skills/ct-epic-architect/references/skill-aware-execution.md +3 -3
  44. package/skills/ct-grade/SKILL.md +3 -4
  45. package/skills/ct-grade/agents/scenario-runner.md +1 -1
  46. package/skills/ct-ivt-looper/SKILL.md +23 -22
  47. package/skills/ct-lead/SKILL.md +52 -13
  48. package/skills/ct-lead/references/aggregation-protocol.md +44 -21
  49. package/skills/ct-lead/references/spawn-pattern.md +12 -11
  50. package/skills/ct-orchestrator/README.md +2 -2
  51. package/skills/ct-orchestrator/SKILL.md +14 -10
  52. package/skills/ct-orchestrator/references/SUBAGENT-PROTOCOL-BLOCK.md +4 -4
  53. package/skills/ct-orchestrator/references/autonomous-operation.md +4 -4
  54. package/skills/ct-orchestrator/references/orchestrator-compliance.md +3 -3
  55. package/skills/ct-orchestrator/references/orchestrator-patterns.md +20 -19
  56. package/skills/ct-orchestrator/references/orchestrator-recovery.md +13 -23
  57. package/skills/ct-orchestrator/references/orchestrator-spawning.md +9 -10
  58. package/skills/ct-orchestrator/references/orchestrator-tokens.md +9 -9
  59. package/skills/ct-provenance-keeper/SKILL.md +10 -7
  60. package/skills/ct-release-orchestrator/SKILL.md +21 -13
  61. package/skills/ct-release-orchestrator/references/composition.md +1 -1
  62. package/skills/ct-release-orchestrator/references/release-types.md +33 -15
  63. package/skills/ct-research-agent/SKILL.md +14 -12
  64. package/skills/ct-research-agent/references/triggers-and-routing.md +4 -4
  65. package/skills/{ct-skill-creator → ct-skill-author}/SKILL.md +9 -6
  66. package/skills/{ct-skill-validator → ct-skill-author}/agents/ecosystem-checker.md +1 -1
  67. package/skills/{ct-skill-validator → ct-skill-author}/evals/quality_evals.json +10 -10
  68. package/skills/{ct-skill-validator → ct-skill-author}/evals/trigger_queries.json +1 -1
  69. package/skills/{ct-skill-validator → ct-skill-author}/references/cleo-ecosystem-rules.md +8 -4
  70. package/skills/{ct-skill-creator → ct-skill-author}/references/provider-deployment.md +10 -6
  71. package/skills/{ct-skill-validator/SKILL.md → ct-skill-author/references/validating.md} +14 -21
  72. package/skills/{ct-skill-validator → ct-skill-author}/references/validation-rules.md +2 -2
  73. package/skills/{ct-skill-validator → ct-skill-author}/scripts/_skill_finder.py +2 -2
  74. package/skills/{ct-skill-validator → ct-skill-author}/scripts/check_depth.py +2 -5
  75. package/skills/{ct-skill-validator → ct-skill-author}/scripts/generate_validation_report.py +1 -1
  76. package/skills/{ct-skill-validator → ct-skill-author}/scripts/run_quality_eval.py +2 -2
  77. package/skills/ct-spec-writer/SKILL.md +9 -7
  78. package/skills/ct-task-executor/SKILL.md +19 -16
  79. package/skills/ct-task-executor/references/common-failures.md +1 -1
  80. package/skills/ct-validator/SKILL.md +11 -9
  81. package/skills/ct-validator/references/compliance-reports.md +1 -1
  82. package/skills/ct-validator/references/validation-modes.md +3 -3
  83. package/skills/manifest.json +381 -365
  84. package/dispatch-config.json +0 -983
  85. package/provider-skills-map.json +0 -97
  86. package/skills/ct-docs-lookup/SKILL.md +0 -185
  87. package/skills/ct-docs-lookup/references/ctx7-workflow.md +0 -198
  88. package/skills/ct-docs-lookup/references/library-id-resolution.md +0 -217
  89. package/skills/ct-docs-lookup/references/version-specific-docs.md +0 -220
  90. package/skills/ct-master-tac/SKILL.md +0 -120
  91. package/skills/ct-master-tac/__tests__/install.test.ts +0 -304
  92. package/skills/ct-master-tac/bundled/README.md +0 -40
  93. package/skills/ct-master-tac/bundled/protocols/architecture-decision.cant +0 -90
  94. package/skills/ct-master-tac/bundled/protocols/artifact-publish.cant +0 -105
  95. package/skills/ct-master-tac/bundled/protocols/consensus.cant +0 -85
  96. package/skills/ct-master-tac/bundled/protocols/contribution.cant +0 -92
  97. package/skills/ct-master-tac/bundled/protocols/decomposition.cant +0 -102
  98. package/skills/ct-master-tac/bundled/protocols/implementation.cant +0 -77
  99. package/skills/ct-master-tac/bundled/protocols/provenance.cant +0 -100
  100. package/skills/ct-master-tac/bundled/protocols/release.cant +0 -107
  101. package/skills/ct-master-tac/bundled/protocols/research.cant +0 -77
  102. package/skills/ct-master-tac/bundled/protocols/specification.cant +0 -77
  103. package/skills/ct-master-tac/bundled/protocols/testing.cant +0 -99
  104. package/skills/ct-master-tac/bundled/protocols/validation.cant +0 -75
  105. package/skills/ct-master-tac/bundled/teams/platform.cant +0 -115
  106. package/skills/ct-master-tac/manifest.json +0 -55
  107. package/skills/ct-skill-creator/eval-viewer/__pycache__/generate_review.cpython-314.pyc +0 -0
  108. package/skills/ct-skill-creator/manifest-entry.json +0 -17
  109. package/skills/ct-skill-creator/scripts/__pycache__/__init__.cpython-314.pyc +0 -0
  110. package/skills/ct-skill-creator/scripts/__pycache__/aggregate_benchmark.cpython-314.pyc +0 -0
  111. package/skills/ct-skill-creator/scripts/__pycache__/generate_report.cpython-314.pyc +0 -0
  112. package/skills/ct-skill-creator/scripts/__pycache__/improve_description.cpython-314.pyc +0 -0
  113. package/skills/ct-skill-creator/scripts/__pycache__/init_skill.cpython-314.pyc +0 -0
  114. package/skills/ct-skill-creator/scripts/__pycache__/quick_validate.cpython-314.pyc +0 -0
  115. package/skills/ct-skill-creator/scripts/__pycache__/run_eval.cpython-314.pyc +0 -0
  116. package/skills/ct-skill-creator/scripts/__pycache__/run_loop.cpython-314.pyc +0 -0
  117. package/skills/ct-skill-creator/scripts/__pycache__/utils.cpython-314.pyc +0 -0
  118. package/skills/ct-skill-validator/manifest-entry.json +0 -20
  119. package/skills/ct-stickynote/README.md +0 -14
  120. package/skills/signaldock-connect/SKILL.md +0 -137
  121. package/skills/signaldock-connect/assets/agent-card.json +0 -48
  122. package/skills/signaldock-connect/references/api-endpoints.md +0 -131
  123. package/skills.json +0 -495
  124. /package/skills/{ct-docs-review → ct-documentor}/references/inline-comment-patterns.md +0 -0
  125. /package/skills/{ct-docs-write → ct-documentor}/references/markdown-patterns.md +0 -0
  126. /package/skills/{ct-skill-creator → ct-skill-author}/agents/analyzer.md +0 -0
  127. /package/skills/{ct-skill-creator → ct-skill-author}/agents/comparator.md +0 -0
  128. /package/skills/{ct-skill-creator → ct-skill-author}/agents/grader.md +0 -0
  129. /package/skills/{ct-skill-creator → ct-skill-author}/assets/eval_review.html +0 -0
  130. /package/skills/{ct-skill-validator → ct-skill-author}/assets/valid-skill-example.md +0 -0
  131. /package/skills/{ct-skill-creator → ct-skill-author}/eval-viewer/generate_review.py +0 -0
  132. /package/skills/{ct-skill-creator → ct-skill-author}/eval-viewer/viewer.html +0 -0
  133. /package/skills/{ct-skill-creator → ct-skill-author}/references/dynamic-context.md +0 -0
  134. /package/skills/{ct-skill-creator → ct-skill-author}/references/frontmatter.md +0 -0
  135. /package/skills/{ct-skill-creator → ct-skill-author}/references/invocation-control.md +0 -0
  136. /package/skills/{ct-skill-creator → ct-skill-author}/references/output-patterns.md +0 -0
  137. /package/skills/{ct-skill-creator → ct-skill-author}/references/schemas.md +0 -0
  138. /package/skills/{ct-skill-creator → ct-skill-author}/references/workflows.md +0 -0
  139. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/__init__.py +0 -0
  140. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/aggregate_benchmark.py +0 -0
  141. /package/skills/{ct-skill-validator → ct-skill-author}/scripts/audit_body.py +0 -0
  142. /package/skills/{ct-skill-validator → ct-skill-author}/scripts/check_ecosystem.py +0 -0
  143. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/generate_report.py +0 -0
  144. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/improve_description.py +0 -0
  145. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/init_skill.py +0 -0
  146. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/package_skill.py +0 -0
  147. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/quick_validate.py +0 -0
  148. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/run_eval.py +0 -0
  149. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/run_loop.py +0 -0
  150. /package/skills/{ct-skill-creator → ct-skill-author}/scripts/utils.py +0 -0
  151. /package/skills/{ct-skill-validator → ct-skill-author}/scripts/validate.py +0 -0
@@ -1,97 +0,0 @@
1
- {
2
- "$schema": "https://lafs.dev/schemas/v1/provider-skills-map.schema.json",
3
- "version": "1.0.0",
4
- "description": "Provider skill path discovery and precedence rules for CLEO skill deployment",
5
- "providers": {
6
- "claude-code": {
7
- "globalSkills": "$HOME/.claude/skills",
8
- "projectSkills": ".claude/skills",
9
- "agentsGlobal": null,
10
- "agentsProject": null,
11
- "readsFromDotAgents": false,
12
- "precedence": "vendor-only",
13
- "symlinkSupported": true,
14
- "notes": "Created Agent Skills standard but uses vendor path exclusively"
15
- },
16
- "codex-cli": {
17
- "globalSkills": "$HOME/.agents/skills",
18
- "projectSkills": ".agents/skills",
19
- "agentsGlobal": "$HOME/.agents/skills",
20
- "agentsProject": ".agents/skills",
21
- "readsFromDotAgents": true,
22
- "precedence": "agents-canonical",
23
- "symlinkSupported": true,
24
- "notes": "Uses .agents/skills as canonical location"
25
- },
26
- "gemini-cli": {
27
- "globalSkills": "$HOME/.gemini/skills",
28
- "projectSkills": ".gemini/skills",
29
- "agentsGlobal": "$HOME/.agents/skills",
30
- "agentsProject": ".agents/skills",
31
- "readsFromDotAgents": true,
32
- "precedence": "agents-first",
33
- "symlinkSupported": true,
34
- "notes": ".agents/skills takes precedence over .gemini/skills within same tier"
35
- },
36
- "cursor": {
37
- "globalSkills": "$HOME/.cursor/skills",
38
- "projectSkills": ".cursor/skills",
39
- "agentsGlobal": null,
40
- "agentsProject": ".agents/skills",
41
- "readsFromDotAgents": "project-only",
42
- "precedence": "vendor-global-agents-project",
43
- "symlinkSupported": true,
44
- "notes": "Global uses vendor path; project supports .agents/skills"
45
- },
46
- "github-copilot": {
47
- "globalSkills": "$HOME/.copilot/skills",
48
- "projectSkills": ".github/skills",
49
- "agentsGlobal": "$HOME/.agents/skills",
50
- "agentsProject": ".agents/skills",
51
- "readsFromDotAgents": true,
52
- "precedence": "agents-supported",
53
- "symlinkSupported": true,
54
- "notes": "Supports both vendor and .agents paths at all levels"
55
- },
56
- "windsurf": {
57
- "globalSkills": "$HOME/.codeium/windsurf/skills",
58
- "projectSkills": ".windsurf/skills",
59
- "agentsGlobal": null,
60
- "agentsProject": null,
61
- "readsFromDotAgents": false,
62
- "precedence": "vendor-only",
63
- "symlinkSupported": false,
64
- "notes": "Vendor-specific paths only, no .agents support"
65
- },
66
- "opencode": {
67
- "globalSkills": "$HOME/.config/opencode/skills",
68
- "projectSkills": ".opencode/skills",
69
- "agentsGlobal": "$HOME/.agents/skills",
70
- "agentsProject": ".agents/skills",
71
- "readsFromDotAgents": true,
72
- "precedence": "agents-supported",
73
- "symlinkSupported": true,
74
- "notes": "User confirms .agents/ support; verify via opencode docs"
75
- },
76
- "kimi-coding": {
77
- "globalSkills": "$HOME/.kimi/skills",
78
- "projectSkills": ".kimi/skills",
79
- "agentsGlobal": null,
80
- "agentsProject": null,
81
- "readsFromDotAgents": false,
82
- "precedence": "vendor-only",
83
- "symlinkSupported": false,
84
- "notes": "Model-based provider; skill path support uncertain"
85
- },
86
- "antigravity": {
87
- "globalSkills": "$HOME/.antigravity/skills",
88
- "projectSkills": ".agent/skills",
89
- "agentsGlobal": null,
90
- "agentsProject": ".agents/skills",
91
- "readsFromDotAgents": "project-only",
92
- "precedence": "vendor-global-agents-project",
93
- "symlinkSupported": true,
94
- "notes": "Project-level .agents/skills confirmed in Google codelabs"
95
- }
96
- }
97
- }
@@ -1,185 +0,0 @@
1
- ---
2
- name: ct-docs-lookup
3
- description: This skill should be used when the user asks "how do I configure [library]", "write code using [framework]", "what are the [library] methods", "show me [framework] examples", or mentions libraries like React, Vue, Next.js, Prisma, Supabase, Express, Tailwind, Drizzle, Svelte. Triggers for library setup, configuration, API references, framework code examples, or version-specific docs ("React 19", "Next.js 15").
4
- version: 1.0.0
5
- core: false
6
- category: composition
7
- protocol: null
8
- dependencies: []
9
- sharedResources: []
10
- compatibility:
11
- - claude-code
12
- - cursor
13
- - windsurf
14
- - gemini-cli
15
- license: MIT
16
- metadata:
17
- version: 1.0.0
18
- tier: on-demand
19
- install: harness
20
- stability: deprecated
21
- ---
22
-
23
- When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data.
24
-
25
- ## When to Use This Skill
26
-
27
- Activate this skill when the user:
28
-
29
- - Asks setup or configuration questions ("How do I configure Next.js middleware?")
30
- - Requests code involving libraries ("Write a Prisma query for...")
31
- - Needs API references ("What are the Supabase auth methods?")
32
- - Mentions specific frameworks (React, Vue, Svelte, Express, Tailwind, etc.)
33
-
34
- ## How to Fetch Documentation
35
-
36
- ### Step 1: Resolve the Library ID
37
-
38
- Call `resolve-library-id` with:
39
-
40
- - `libraryName`: The library name extracted from the user's question
41
- - `query`: The user's full question (improves relevance ranking)
42
-
43
- ### Step 2: Select the Best Match
44
-
45
- From the resolution results, choose based on:
46
-
47
- - Exact or closest name match to what the user asked for
48
- - Higher benchmark scores indicate better documentation quality
49
- - If the user mentioned a version (e.g., "React 19"), prefer version-specific IDs
50
-
51
- ### Step 3: Fetch the Documentation
52
-
53
- Call `query-docs` with:
54
-
55
- - `libraryId`: The selected Context7 library ID (e.g., `/vercel/next.js`)
56
- - `query`: The user's specific question
57
-
58
- ### Step 4: Use the Documentation
59
-
60
- Incorporate the fetched documentation into your response:
61
-
62
- - Answer the user's question using current, accurate information
63
- - Include relevant code examples from the docs
64
- - Cite the library version when relevant
65
-
66
- ## Guidelines
67
-
68
- - **Be specific**: Pass the user's full question as the query for better results
69
- - **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step
70
- - **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks
71
-
72
- ## Why Context7 (not training data)
73
-
74
- The user's global rule is explicit: prefer Context7 over training data for any
75
- library, framework, SDK, API, CLI tool, or cloud service — even well-known ones
76
- like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This
77
- includes API syntax, configuration, version migration, library-specific
78
- debugging, setup instructions, and CLI tool usage. Use even when you think
79
- you know the answer; training data may not reflect recent changes.
80
-
81
- ## Three-Command Budget
82
-
83
- The user rules cap a docs lookup at three CLI invocations per question. The
84
- budget fits the standard workflow:
85
-
86
- 1. `npx ctx7@latest library "<name>" "<question>"` — one call to resolve.
87
- 2. `npx ctx7@latest docs <id> "<question>"` — one call to fetch.
88
- 3. (Optional) `npx ctx7@latest docs <id> "<question>" --research` — one
89
- retry with sandboxed agents pulling source + web search.
90
-
91
- Going over budget is a signal: the library name is wrong, the question
92
- is too broad, or Context7 doesn't cover this library. In any of those
93
- cases, refine before retrying — don't burn more calls.
94
-
95
- ## When NOT to Use This Skill
96
-
97
- The user rules explicitly exclude these from docs-lookup:
98
-
99
- - **Refactoring** — re-shaping existing code; no library lookup needed.
100
- - **Scripts written from scratch** — general programming, not library API.
101
- - **Debugging business logic** — use codebase tools (Grep, GitNexus), not
102
- external docs.
103
- - **Code review** — quality assessment, not library reference.
104
- - **General programming concepts** — pure CS questions; training data is fine.
105
-
106
- Use docs-lookup ONLY for: API syntax, configuration questions, version
107
- migration issues, library-specific debugging, setup instructions, and CLI
108
- tool usage.
109
-
110
- ## Authentication and Quotas
111
-
112
- The `ctx7` CLI runs anonymously with a limited free quota. When quota
113
- exhausts:
114
-
115
- ```text
116
- Error: Quota exceeded.
117
- Run `npx ctx7@latest login` for higher limits.
118
- Or set CONTEXT7_API_KEY env var with your key.
119
- ```
120
-
121
- Surface the error to the user (or include in `needs_followup`). NEVER
122
- silently fall back to training data — that violates the skill's contract.
123
-
124
- ## Sensitive Data
125
-
126
- Queries to Context7 are logged on the Context7 side. Never include:
127
-
128
- - API keys, tokens, passwords
129
- - Internal hostnames or URLs
130
- - Customer-identifying data
131
- - Source code excerpts from private repos
132
-
133
- Use generic phrasing. If the actual API call needs a specific value,
134
- describe it abstractly ("how do I authenticate with an API key" instead
135
- of "use API key sk_live_abc123 to...").
136
-
137
- ## Multi-Library Composition
138
-
139
- A single question may touch multiple libraries — common in modern stacks
140
- (SvelteKit + Better-Auth + Drizzle, Next.js + Prisma + Tailwind, etc.).
141
- Resolve each library independently with the right version pin, then
142
- synthesize.
143
-
144
- The three-command budget applies per-library; a question spanning
145
- three libraries gets nine commands. Stay focused — fetch the specific
146
- integration point each time, not the entire library surface.
147
-
148
- ## Citing Versions in Answers
149
-
150
- Every code example produced from a version-pinned fetch MUST cite the
151
- version. The reader copies the code and runs it; when their version
152
- differs, the citation is the first thing they check.
153
-
154
- ```markdown
155
- Use `defineRelations` (Drizzle ORM v1.0.0-beta and later):
156
-
157
- ```typescript
158
- import { defineRelations } from "drizzle-orm";
159
- // ...
160
- ```
161
- ```
162
-
163
- Without the version note, the reader who is on Drizzle 0.x will be
164
- confused when the import fails.
165
-
166
- ## Common Failure Modes
167
-
168
- | Symptom | Cause | Fix |
169
- |---------|-------|-----|
170
- | "Library not found" | Wrong name format | Use official punctuation: "Next.js" not "nextjs" |
171
- | Stale answer | No version pin | Detect installed version from lockfile, pin |
172
- | Generic answer when specifics needed | Vague query | Pass full question text, not single words |
173
- | Quota exceeded | Anonymous over-use | `ctx7 login` or set `CONTEXT7_API_KEY` |
174
- | Hallucinated API | Skipped Context7 | Always run Step 1+2 before answering library questions |
175
- | Wrong fork picked | Took top result blindly | Read descriptions; prefer official org |
176
-
177
- ---
178
-
179
- ## See references/
180
-
181
- Progressive disclosure — load on demand only:
182
-
183
- - `references/ctx7-workflow.md` — two-step loop, query formatting, research mode, budget
184
- - `references/library-id-resolution.md` — signals for picking the right ID; disambiguation procedure
185
- - `references/version-specific-docs.md` — version pinning, migrations, deprecations, drift detection
@@ -1,198 +0,0 @@
1
- # ctx7 Workflow
2
-
3
- `ct-docs-lookup` is the CLEO-side wrapper around the `ctx7` CLI. The
4
- underlying contract is set in the user's global rules
5
- (`~/.claude/rules/context7.md`) and the project's `MCP_Context7.md`.
6
- This reference codifies the workflow with concrete examples and
7
- recovery procedures.
8
-
9
- ## Why Context7
10
-
11
- The skill's purpose statement is direct: when the user asks about a
12
- library, framework, or needs code examples, fetch current documentation
13
- instead of relying on training data. Training data is stale — the
14
- project's user rules say so explicitly.
15
-
16
- This applies even when you think you know the answer. API surfaces of
17
- React, Next.js, Prisma, Tailwind, Drizzle, Svelte, Supabase, and friends
18
- move faster than any model's cutoff. Verify against current docs.
19
-
20
- ## The Two-Step Loop
21
-
22
- The ctx7 CLI is shipped as `npx ctx7@latest`. The workflow is two calls.
23
-
24
- ```bash
25
- # Step 1 — resolve the official library ID
26
- npx ctx7@latest library "<library-name>" "<user-question>"
27
-
28
- # Step 2 — fetch docs for the resolved ID
29
- npx ctx7@latest docs <libraryId> "<user-question>"
30
- ```
31
-
32
- The output of Step 1 is a list of candidate library IDs in the form
33
- `/org/project`. Pick the best match (see `library-id-resolution.md` for
34
- the heuristics) and pass it to Step 2.
35
-
36
- ## Step 1: Library Resolution
37
-
38
- Use the official library name with proper punctuation:
39
-
40
- | ❌ Wrong | ✅ Correct |
41
- |----------|------------|
42
- | `"nextjs"` | `"Next.js"` |
43
- | `"customerio"` | `"Customer.io"` |
44
- | `"threejs"` | `"Three.js"` |
45
- | `"reactdom"` | `"React DOM"` |
46
- | `"vuejs"` | `"Vue.js"` |
47
- | `"tailwindcss"` | `"Tailwind CSS"` |
48
-
49
- The library name matches what the project documents itself as. When
50
- unsure, search the project's GitHub README for the official name.
51
-
52
- Pass the user's full question as the second arg — specific queries
53
- return better matches than single words.
54
-
55
- ```bash
56
- # GOOD
57
- npx ctx7@latest library "Drizzle ORM" "how do I define relations in v1"
58
-
59
- # BAD — too generic, ranks poorly
60
- npx ctx7@latest library "drizzle" "relations"
61
- ```
62
-
63
- ## Step 1 Output Interpretation
64
-
65
- The CLI returns candidates with several signals — pick by:
66
-
67
- 1. **Exact name match.** "Next.js" should resolve to `/vercel/next.js`
68
- over `/some-fork/next.js-clone`.
69
- 2. **Source reputation.** Look for High or Medium source labels.
70
- 3. **Code snippet count.** More snippets = better-indexed library.
71
- 4. **Benchmark score.** Higher is better; reflects retrieval quality.
72
-
73
- If the top candidate doesn't match exactly what the user asked for —
74
- e.g., they said "Next.js 15" and the top candidate is generic — try
75
- again with refined terms or version-specific names.
76
-
77
- ## Step 2: Docs Fetch
78
-
79
- Once you have the library ID:
80
-
81
- ```bash
82
- npx ctx7@latest docs /vercel/next.js "how do I configure middleware to inject auth headers"
83
- ```
84
-
85
- The output is documentation excerpts with citations. Use these directly
86
- in your answer — they are current, sourced, and citable.
87
-
88
- ## Version-Specific Docs
89
-
90
- When the user names a version, use the version-specific form:
91
-
92
- ```bash
93
- # General
94
- npx ctx7@latest docs /vercel/next.js "..."
95
-
96
- # Pinned to v14.3.0
97
- npx ctx7@latest docs /vercel/next.js/v14.3.0 "..."
98
-
99
- # Pinned to v15 (latest 15.x)
100
- npx ctx7@latest docs /vercel/next.js/v15 "..."
101
- ```
102
-
103
- The Step 1 output enumerates available versions. Pick the version
104
- matching the project's actual installed version (check
105
- `package.json` / `Cargo.toml` / `requirements.txt`).
106
-
107
- ## Research Mode (Fallback)
108
-
109
- If the default fetch doesn't satisfy the question, retry with
110
- `--research`:
111
-
112
- ```bash
113
- npx ctx7@latest docs /vercel/next.js "..." --research
114
- ```
115
-
116
- This launches sandboxed agents that git-pull the actual source repos
117
- plus live web search, then synthesizes a fresh answer. More costly
118
- (longer, more tokens), so use only when:
119
-
120
- - Default fetch returned a generic answer when specifics were needed.
121
- - The question references a recent change that may not be indexed yet.
122
- - The user explicitly asked for research-grade depth.
123
-
124
- ## Auth and Quotas
125
-
126
- The `ctx7` CLI runs anonymously by default with limited quota. When
127
- quota is exhausted:
128
-
129
- ```bash
130
- # Error message will be something like:
131
- # Error: Quota exceeded. Run `npx ctx7@latest login` or set CONTEXT7_API_KEY
132
- ```
133
-
134
- Instruct the user (or surface in `needs_followup`) to either:
135
- - Run `npx ctx7@latest login` (one-time browser auth)
136
- - Set `CONTEXT7_API_KEY` env var with their key
137
-
138
- Do NOT silently fall back to training data — that violates the skill's
139
- contract. The whole point is current docs, not stale recall.
140
-
141
- ## Budget Discipline
142
-
143
- The user rules cap the workflow at "no more than 3 commands per
144
- question". For most lookups this is plenty:
145
- - 1 call: library resolution
146
- - 1 call: docs fetch
147
- - 1 call (optional): retry with `--research` if needed
148
-
149
- Going over budget signals one of:
150
- - Wrong library name (refine and retry)
151
- - Question too broad (narrow the question first)
152
- - Genuine library mismatch (Context7 doesn't cover this library — use
153
- web search via WebSearch/WebFetch as alternative)
154
-
155
- ## Sensitive Data
156
-
157
- Never include API keys, passwords, credentials, or internal URLs in
158
- queries. The query is logged on the Context7 side.
159
-
160
- ```bash
161
- # WRONG
162
- npx ctx7@latest docs /supabase/supabase "use API key sk_live_abc123 to..."
163
-
164
- # RIGHT
165
- npx ctx7@latest docs /supabase/supabase "how do I authenticate the client with an API key"
166
- ```
167
-
168
- ## End-to-End Example
169
-
170
- ```bash
171
- # User asked: "How do I do streaming server actions in Next.js 15?"
172
-
173
- # Step 1 — resolve
174
- $ npx ctx7@latest library "Next.js" "How do I do streaming server actions in Next.js 15?"
175
- > /vercel/next.js/v15 (benchmark 0.87, snippets 1240, source: High)
176
- > /vercel/next.js (benchmark 0.85, snippets 5230, source: High)
177
- > ...
178
-
179
- # Step 2 — fetch (use version-pinned ID)
180
- $ npx ctx7@latest docs /vercel/next.js/v15 "How do I do streaming server actions in Next.js 15?"
181
- > [docs excerpt with streaming example, citation]
182
-
183
- # Compose answer using the fetched docs, citing version
184
- ```
185
-
186
- ## When NOT to Use This Skill
187
-
188
- See `library-id-resolution.md` for the boundary with debugging tasks,
189
- and `version-specific-docs.md` for when the answer doesn't depend on
190
- a specific library. Quick summary:
191
-
192
- - ❌ Don't use for refactoring (no library lookup needed)
193
- - ❌ Don't use for scripts written from scratch
194
- - ❌ Don't use for debugging business logic (use codebase tools)
195
- - ❌ Don't use for code review
196
- - ❌ Don't use for general programming concepts
197
- - ✅ Use for API syntax, configuration, version migration, library-specific
198
- debugging, setup instructions, CLI tool usage
@@ -1,217 +0,0 @@
1
- # Library ID Resolution
2
-
3
- The Context7 library catalog uses `/org/project` IDs. Picking the right
4
- ID is the difference between fetching authoritative docs and fetching
5
- a community fork's stale README. This reference codifies the
6
- disambiguation heuristics with concrete examples.
7
-
8
- ## ID Anatomy
9
-
10
- ```
11
- /vercel/next.js
12
- └org─┘ └proj─┘
13
-
14
- /vercel/next.js/v14.3.0
15
- └org─┘ └proj─┘ └version┘
16
- ```
17
-
18
- - The `org` is typically the GitHub org or the company name.
19
- - The `project` is the official package name.
20
- - The optional `version` is a tag or release branch.
21
-
22
- ## Resolution Output Format
23
-
24
- A typical Step 1 (`ctx7 library`) output:
25
-
26
- ```text
27
- Top matches for "Next.js" against query "configure middleware":
28
-
29
- 1. /vercel/next.js
30
- - Source: High
31
- - Description: The React Framework for the Web.
32
- - Code snippets: 5230
33
- - Benchmark: 0.85
34
-
35
- 2. /vercel/next.js/v15
36
- - Source: High
37
- - Description: Next.js v15 release line.
38
- - Code snippets: 1240
39
- - Benchmark: 0.87
40
-
41
- 3. /community/next-with-foo
42
- - Source: Medium
43
- - Description: Next.js + Foo starter template.
44
- - Code snippets: 87
45
- - Benchmark: 0.42
46
-
47
- 4. /old-org/nextjs-legacy
48
- - Source: Low
49
- - Description: Pre-app-router Next.js patterns.
50
- - Code snippets: 412
51
- - Benchmark: 0.39
52
- ```
53
-
54
- Five signals to weigh.
55
-
56
- ## Signal 1: Exact Name Match
57
-
58
- The user said "Next.js". Candidates 1 and 2 are exact matches; 3 is
59
- "next-with-foo" (a derivative); 4 is "nextjs-legacy" (suffixed).
60
-
61
- Prefer the canonical name. The derivative or suffixed projects are
62
- appropriate ONLY when the user explicitly named them.
63
-
64
- ## Signal 2: Source Reputation
65
-
66
- `High` > `Medium` > `Low`. Source reputation reflects how authoritative
67
- Context7 considers the project. Official org-owned repos are High.
68
- Community forks are typically Medium. Abandoned or low-quality projects
69
- are Low.
70
-
71
- When multiple High candidates exist, look further. When the only
72
- High candidate is the obvious one, pick it.
73
-
74
- ## Signal 3: Code Snippet Count
75
-
76
- More snippets = better-indexed library = higher chance of finding the
77
- exact API the user asked about. The unversioned ID usually has higher
78
- snippet counts than version-pinned IDs because it aggregates across
79
- versions.
80
-
81
- For general questions, prefer unversioned IDs. For version-specific
82
- questions, accept the lower snippet count of the pinned ID.
83
-
84
- ## Signal 4: Benchmark Score
85
-
86
- The benchmark is a retrieval-quality measure produced by Context7 —
87
- higher means the candidate library has good documentation that
88
- indexes well. Use as a tiebreaker only.
89
-
90
- In the example above, candidate 2 has a slightly higher benchmark
91
- (0.87) than candidate 1 (0.85) because v15-specific queries score
92
- better against the pinned slice. For a v15-specific question, prefer
93
- candidate 2.
94
-
95
- ## Signal 5: Query Alignment
96
-
97
- The user's query in Step 1 affects ranking. If the query mentioned
98
- "middleware", candidates whose docs cover middleware will rank higher.
99
- This is why passing the FULL user question (not a single word) yields
100
- better resolution.
101
-
102
- ## Common Pitfalls
103
-
104
- ### Pitfall: Picking the version-pinned ID for a general question
105
-
106
- The user asked "What does Next.js do?" — a general question.
107
-
108
- - ❌ Pick `/vercel/next.js/v15` — too narrow; misses cross-version context.
109
- - ✅ Pick `/vercel/next.js` — covers the whole project.
110
-
111
- ### Pitfall: Picking the unversioned ID for a version-specific question
112
-
113
- The user asked "How do I migrate from Next.js 14 to 15?"
114
-
115
- - ❌ Pick `/vercel/next.js` — might return mixed-version docs.
116
- - ✅ Pick `/vercel/next.js/v15` — gets the migration guide for 15.
117
- - ✅ Better: pick `/vercel/next.js/v15` for "to" and `/vercel/next.js/v14`
118
- for "from", and run two fetches.
119
-
120
- ### Pitfall: Picking the community fork when the user wants the official
121
-
122
- The user asked "How do I use Tailwind utilities?"
123
-
124
- - ❌ Pick `/some-community/tailwind-with-extras` — not what they meant.
125
- - ✅ Pick `/tailwindlabs/tailwindcss` — the official.
126
-
127
- Community forks rank LOW on the "what user meant" axis even when they
128
- rank high on other signals. Default to the official.
129
-
130
- ### Pitfall: Picking the highest snippet count regardless of relevance
131
-
132
- The user asked about Vue 3 composition API.
133
-
134
- - ❌ Pick `/vuejs/vue` (high snippet count, but it's the Vue 2 line).
135
- - ✅ Pick `/vuejs/core` or `/vuejs/vue-next` (Vue 3).
136
-
137
- Always read the description, not just the count. Old projects accumulate
138
- snippets because they've been around longer — they may no longer be
139
- current.
140
-
141
- ## Disambiguation Procedure
142
-
143
- When two candidates look equally good:
144
-
145
- 1. **Read the descriptions.** They usually disambiguate.
146
- 2. **Check the org.** Official org = the project's home; community
147
- org = derivative.
148
- 3. **Check the project's GitHub URL** if Context7 includes it. The URL
149
- matches what the project's README cites.
150
- 4. **Try both.** Compare the outputs of Step 2 for each candidate. The
151
- one that better answers the question is the right one.
152
-
153
- ## When Resolution Fails
154
-
155
- Sometimes Step 1 returns no good match. The library may not be in
156
- Context7's catalog, or the name was wrong. Recovery:
157
-
158
- ```bash
159
- # Retry with the formal name from the project's GitHub
160
- npx ctx7@latest library "TanStack Query" "..." # not "react-query"
161
-
162
- # Retry with the alternative spelling
163
- npx ctx7@latest library "GitHub Actions" "..." # not "gh-actions"
164
-
165
- # Retry with a more specific query
166
- npx ctx7@latest library "Next.js" "App Router middleware in v15"
167
-
168
- # If all retries fail, fall back to WebSearch / WebFetch
169
- # (but tell the user the library isn't in Context7's catalog)
170
- ```
171
-
172
- ## Version Resolution Specifics
173
-
174
- When a project has many versions, Step 1's output lists them. Pick by:
175
-
176
- 1. **Match the project's installed version.** Check `package.json`,
177
- `Cargo.toml`, `requirements.txt`, etc.
178
- 2. **If the user named a version, use that.**
179
- 3. **If neither, use the latest stable (highest version number that
180
- isn't pre-release).**
181
-
182
- ```bash
183
- # Project installed Next.js 14.3.x
184
- $ jq '.dependencies.next' package.json
185
- "14.3.0"
186
-
187
- # Use the pinned version
188
- npx ctx7@latest docs /vercel/next.js/v14.3.0 "..."
189
- ```
190
-
191
- This catches the case where the user asks about behavior that differs
192
- between versions; using the wrong version pin gives a confidently
193
- wrong answer.
194
-
195
- ## Caching
196
-
197
- Library IDs rarely change. If you resolved `/vercel/next.js/v15` for
198
- one query, you can re-use it for the next query about the same library
199
- without running Step 1 again. Just remember to refresh the resolution
200
- when:
201
-
202
- - Asking about a different major version.
203
- - The project's installed version changed.
204
- - The previous fetch didn't satisfy the question (maybe the wrong ID
205
- was picked).
206
-
207
- ## When NOT to Use Library Lookup
208
-
209
- The user rules are explicit: not for refactoring, scripts-from-scratch,
210
- business-logic debugging, code review, or general programming concepts.
211
-
212
- If the question is "how do I structure my repository?" — that is a
213
- general programming question. Use general knowledge plus codebase
214
- inspection, not Context7.
215
-
216
- If the question is "how does Next.js's app router handle parallel
217
- routes?" — that is a library API question. Use Context7.