Skip to content
Back to search

context-docs

SkillWorks with CodexGitHub

Agent skills for Codex and Claude Code that preserve project context, decisions and next steps across AI sessions in plain Markdown.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 12 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jaredchu/context-docs with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jaredchu/context-docs'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jaredchu--context-docs/badge.svg)](/listings/jaredchu--context-docs)

HTML

<a href="/listings/jaredchu--context-docs"><img src="/api/listings/jaredchu--context-docs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Ask Codex:

Use $skill-installer to install both skills from jaredchu/context-docs
at the published tag v0.2.7:
- skills/context-docs
- skills/adopt-context-docs
Install them together in ~/.agents/skills/.
Preserve existing installations and local customizations; report version
mismatches before upgrading. Report the installed VERSION values:
context-docs 0.2.7 and adopt-context-docs 0.1.16.

[Manual installation and project-only setup →](docs/getting-started.md#install-in-codex)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 273 lines
  1. # Context Docs
  2. **Keep decisions, current work and next steps across AI sessions.**
  3. Context Docs provides reusable agent skills for context management in Codex and
  4. Claude Code. Preserve project knowledge in readable Markdown so a new AI session
  5. can pick up where you left off: what was decided and why, what is done or blocked,
  6. and what to do next.
  7. Designed for people without an established context-management workflow, it uses
  8. your project's existing documents with as little setup and manual organization
  9. as possible.
  10. **Vibe coding with AI prompts?** Start with one useful note or keep your existing
  11. PRD, design and task files. Review the context updates as you build, then ask your
  12. next session to read them.
  13. ![Illustrative workflow: do the work, save decisions and reasons, current work and next steps in project Markdown, then ask a new session to read the saved note and check the project. The agent works during active sessions; review its changes.](assets/context-docs-overview.png)
  14. [Website](https://context-docs.com/) · [Get started](#get-started) · [See an example](#what-you-get) · [User guide](docs/getting-started.md) · [Evidence](docs/evaluation-results.md) · [Contribute](CONTRIBUTING.md)
  15. **Status: experimental, core skill v0.2.7 and adoption skill v0.1.16.**
  16. The [v0.2.7 release notes](docs/releases/v0.2.7.md) cover a narrow instruction
  17. simplification and qualified checks. Everyday installation selects this bundle.
  18. The Codex candidate report's automatic-loading confirmation remains unverified;
  19. Claude instruction events support loading in its checked sessions only.
  20. The [v0.2.6 release notes](docs/releases/v0.2.6.md) cover metadata filtering,
  21. portable references and qualified synthetic checks. The earlier candidate’s
  22. unlinked-note coverage gap remains; the separate installed check names the note
  23. explicitly. See [results and qualifications](docs/evaluation-results.md#more-recent-studies).
  24. Publication and installation are separate actions. See [release history](docs/releases/README.md) for earlier
  25. versions, feature boundaries and retained evidence.
  26. For Codex and Claude Code · Plain Markdown · [MIT licensed](LICENSE)
  27. ## What you get
  28. You should not have to invent a documentation system before you can preserve your
  29. work. Context Docs gives your agent instructions to:
  30. - **Save what matters:** decisions and their reasons, current work, blockers and next steps.
  31. - **Keep it useful:** update stale sections, consolidate repetition and distinguish facts from proposals.
  32. - **Fit your project:** use existing documents and choose content for their audience.
  33. - **Help the next session start:** make the context discoverable from the README or documentation index.
  34. - **See progress in Markdown:** show the documented goal, meaningful advances,
  35. blockers and next action in an existing section or a linked Markdown view.
  36. For example, after working on an export feature, your project context might contain:
  37. ```markdown
  38. ## Current work
  39. CSV export is implemented; empty-input behavior still needs testing.
  40. ## Decision (maintainer-approved)
  41. Keep the existing export API to preserve compatibility.
  42. ## Next step
  43. Test empty input before calling the feature complete.
  44. ```
  45. *Illustrative content, not a required template.* The agent should derive entries
  46. from your actual work and evidence. You review the changes; the next session
  47. reads the saved context. See a fuller [before-and-after example](examples/maintenance.md).
  48. Explore the [worked examples](https://context-docs.com/examples/): the
  49. [Reading Queue walkthrough](https://context-docs.com/examples/reading-queue/) teaches
  50. the full workflow; separate [Codex → Claude Code](https://context-docs.com/examples/switching-codex-claude/)
  51. and [Claude Code → Codex](https://context-docs.com/examples/switching-claude-codex/)
  52. cases show how to hand off the same project through saved Markdown.
  53. ## Get started
  54. Install both skills, then adopt them in the project you want to maintain.
  55. Already installed? Skip to [Use it](#use-it).
  56. The instructions below select published bundle **v0.2.7**: core **0.2.7** and
  57. adoption **0.1.16**. See the [guide](docs/getting-started.md#development-source-installs)
  58. for development-source installations.
  59. ### Install in Codex
  60. Ask Codex:
  61. ```text
  62. Use $skill-installer to install both skills from jaredchu/context-docs
  63. at the published tag v0.2.7:
  64. - skills/context-docs
  65. - skills/adopt-context-docs
  66. Install them together in ~/.agents/skills/.
  67. Preserve existing installations and local customizations; report version
  68. mismatches before upgrading. Report the installed VERSION values:
  69. context-docs 0.2.7 and adopt-context-docs 0.1.16.
  70. ```
  71. [Manual installation and project-only setup →](docs/getting-started.md#install-in-codex)
  72. ### Install in Claude Code
  73. For a first installation, run these commands in a terminal:
  74. ```sh
  75. git clone --branch v0.2.7 https://github.com/jaredchu/context-docs.git
  76. cd context-docs
  77. mkdir -p ~/.claude/skills
  78. cp -r skills/context-docs skills/adopt-context-docs ~/.claude/skills/
  79. cat ~/.claude/skills/context-docs/VERSION ~/.claude/skills/adopt-context-docs/VERSION
  80. ```
  81. If either skill is already installed, [review the upgrade guidance](docs/getting-started.md#upgrading)
  82. before copying files. [Project-only setup and instruction loading →](docs/getting-started.md#install-in-claude-code)
  83. The version output should be `0.2.7` followed by `0.1.16`.
  84. ## Use it
  85. ### 1. Set up your project
  86. Open your project in your coding agent and invoke:
  87. | Codex | Claude Code |
  88. | --- | --- |
  89. | `$adopt-context-docs` | `/adopt-context-docs` |
  90. The adoption skill applies the context workflow and adds or reuses a maintenance
  91. rule in the project instructions your agent loads. It preserves equivalent
  92. existing rules and the project’s documentation layout, and reports when it cannot
  93. confirm instruction loading.
  94. Adoption directs the agent to start a simple inline progress path by default when
  95. the documented goal and work support one, including during explicit re-adoption.
  96. The guidance reuses existing views and keeps them current during everyday context
  97. updates, without a second task list or repeated requests. Installation and upgrade
  98. alone do not rewrite existing project setups.
  99. If setup or saved context seems wrong, use the
  100. [read-only troubleshooting prompt](docs/getting-started.md#troubleshoot-setup-and-saved-context).
  101. ### 2. Save decisions, current work and next steps
  102. Once adopted, the project's loaded maintenance rule guides the agent to update
  103. context after meaningful changes during normal work. You do not need to name
  104. Context Docs in every prompt. Check that the rule is loaded and review the updates.
  105. If an update is missed, or you want one explicitly, ask:
  106. ```text
  107. Update this project's context from the work we just completed.
  108. Preserve decisions and their reasons, current work, blockers and next steps.
  109. ```
  110. Review the resulting diff. You do not need to keep a session diary or log every
  111. interaction. For shared Git context, include relevant context changes alongside
  112. code in your already-authorized commit/transfer workflow, and confirm the other
  113. checkout has those files before resuming. For ignored local-only context, use
  114. your existing private transfer/backup procedure; it does not travel with a clone.
  115. If work accumulated outside the current session, use the same skill
  116. to refresh context against current evidence:
  117. ```text
  118. Use context-docs to refresh this project's context against current project evidence.
  119. ```
  120. This uses existing maintenance guidance; no new skill or re-adoption is needed.
  121. See the [refresh guidance and focused check](docs/getting-started.md#refresh-after-outside-work).
  122. To inspect documentation without changing it, ask:
  123. ```text
  124. Use context-docs to audit this project's context documents without editing files.
  125. ```
  126. ### 3. Resume with the saved context
  127. Start a new session with:
  128. ```text
  129. Read this project's context entry point and its relevant linked documents.
  130. Use the recorded decisions, current work and next steps to continue with the next task.
  131. ```
  132. Find the entry point in your README, documentation index, or the adoption marker’s
  133. `Entry point:` field. Explicitly
  134. ask the agent to read it: a saved file alone does not ensure that a new session
  135. loads it. To check what a new session takes from the saved note, use the optional
  136. [read-only verification prompt](docs/getting-started.md#verify-a-resumed-session).
  137. [More usage examples and setup details →](docs/getting-started.md#use-it)
  138. This also applies when switching between Codex and Claude Code. Save and review
  139. context before switching, open the same code and notes in the receiving client,
  140. and confirm its maintenance instructions load. See the
  141. [direction-specific walkthroughs](https://context-docs.com/examples/) and their
  142. [observed checks and limits](docs/switching-agents-examples.md).
  143. ### 4. Visualize progress in Markdown
  144. The skills add a progress view without a web app or separate tracker:
  145. ```text
  146. Use context-docs to visualize this project's progress in Markdown.
  147. Show the documented goal, completed and blocked work, meaningful advances
  148. and next action as a compact visual path. Show dependencies and put blockers
  149. beside the work they stop. Link to sources and mark unknowns. Reuse the
  150. existing context layout, or link a separate Markdown file if that reads better.
  151. ```
  152. The guidance directs the agent to maintain an existing view during authorized
  153. context updates and distinguish activity, useful learning and completed outcomes.
  154. A possible stall requires relevant historical evidence; invented completion
  155. percentages and claims of live agent activity are forbidden.
  156. Favor a concise tree, arrow path or nested checklist with dependencies and blockers
  157. visible, linking to detailed evidence while preserving decisions and existing
  158. layouts. A flat status table alone is insufficient; there is no fixed length limit.
  159. See the [guide](docs/getting-started.md#progress-in-markdown),
  160. [synthetic example](examples/progress.md) and
  161. [qualified checks](docs/evaluation-results.md#more-recent-studies).
  162. ## Two skills, one workflow
  163. | Skill | When to use it |
  164. | --- | --- |
  165. | [adopt-context-docs](skills/adopt-context-docs/SKILL.md) | Set up the workflow and ongoing maintenance rule in a project. Requires the sibling core skill. |
  166. | [context-docs](skills/context-docs/SKILL.md) | Create, maintain or audit project context. Can also be used on its own. |
  167. Ordinary maintenance requires no background service, cloud account or runtime
  168. dependency. The agent works during active sessions; this is not automatic
  169. conversation capture or unlimited memory. Your project keeps ordinary, reviewable files.
  170. ## Optional logging
  171. Most users can start with Markdown context alone. An optional event journal can
  172. record significant history for later investigation, including when local-only
  173. context changes without Git history. It is off by default unless you explicitly
  174. enable it or select the auto preference. With no project logging setting, auto
  175. applies outside Git or to explicitly selected local-only context with verified
  176. ignored, untracked context and journal paths. Installing the skills does not enable
  177. it. The journal helper requires Python 3.9+.
  178. [Logging setup, upgrades and auto preference →](docs/getting-started.md#optional-logging)
  179. Prefer context that stays out of Git? Select the opt-in
  180. [local-only setup](docs/getting-started.md#local-only-context-excluded-from-git).
  181. Existing setups are preserved.
  182. ## Quality and limits
  183. The goal is useful, accurate context with less effort for people who lack an
  184. established workflow. The project has packaging checks and recorded agent
  185. studies, including failures and reviewer disagreements. Those studies do not yet
  186. establish effort savings for the intended users or a skill-specific correctness
  187. advantage. Comparisons with competent
  188. ordinary maintenance are quality diagnostics, not a requirement to beat experts.
  189. The skill guides an agent; it cannot guarantee factual correctness or complete
  190. preservation, and it cannot prevent concurrent editing conflicts. Review
  191. consequential claims and edits. It provides no automatic scheduler and grants no
  192. permission to publish documents or change other systems. Native integration
  193. remains experimental.
  194. [Results, methods and limitations →](docs/evaluation-results.md)
  195. ## Explore
  196. - [Who Context Docs fits and how it compares](docs/context-management-comparison.md) · [Live comparison](https://context-docs.com/compare/)
  197. - [Installation and usage](docs/getting-started.md) · [Release history](docs/releases/README.md) · [Changelog](CHANGELOG.md)
  198. - [Context standard](skills/context-docs/references/standard.md) · [Context template](skills/context-docs/assets/project-context.md) · [Decision template](skills/context-docs/assets/decision-record.md)
  199. - [Contributing](CONTRIBUTING.md) · [Case and review templates](evals/external-validation/README.md)
  200. - [Evaluation scenarios](evals/README.md) · [This project’s context](docs/project-context.md)
  201. ## Credits and license
  202. Created and maintained by [Jared Chu](https://github.com/jaredchu), with
  203. [OpenAI Codex](https://github.com/codex) and Claude contributing implementation,
  204. documentation and evaluations. Codex led the initial AI development.
  205. See the [contribution and attribution policy](CONTRIBUTING.md).
  206. Released under the [MIT license](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.