document skill
✓ VerifiedRecords technical decisions, documents existing code, or files research material into structured document types like ADRs, RFCs, or specs.
- GitHub stars
- 75
- Files
- 1
- Last commit
- Nov 7, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the document skill do?
document records technical decisions, documents existing code, or files research material into structured document types like ADRs, RFCs, or specs.
Summary generated from the skill's SKILL.md.
About the document skill
Technical teams can use this skill to capture the present state of their architecture, whether they are recording a settled decision, documenting existing code, or filing research material. It serves as a structured repository for knowledge, transforming free text into formal document types like ADRs, RFCs, specifications, or guides. When an agent receives a request to document a module or a decision, it identifies the correct track—decision, code-doc, or research—to ensure the output follows the appropriate organizational standards.
The tool relies on a system of contracts and gates to classify requests and find the correct document owners. It can search for existing documents in a local directory to offer updates instead of creating duplicates. By loading specific compatibility and precision rules, it ensures that technical documentation remains consistent. It is specifically designed for recording what currently exists or what has been decided, distinguishing itself from planning tools that focus on future deltas or review tools that audit documentation health.
What an agent can do with it
- 1Record technical decisionsAn agent can formalize a team's choice to use a specific technology by creating an ADR.
- 2Document existing codebasesDevelopers can use the skill to generate descriptions or guides for complex system modules.
- 3File research and evidenceThe skill can be used to archive benchmark reports or external vendor documents for future reference.
- 4Draft technical proposalsUsers can initiate the RFC process to propose significant architectural changes.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the document skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the document skill in Plugin
/plugin marketplace add archcore-ai/archcore /plugin install archcore@archcore-plugins
Install the document skill in Claude Code
~/.claude/skills/document/SKILL.md
$ npx degit archcore-ai/archcore/plugins/archcore/skills/document ~/.claude/skills/documentInstall the document skill in Claude Code (project)
.claude/skills/document/SKILL.md
$ npx degit archcore-ai/archcore/plugins/archcore/skills/document .claude/skills/documentInstall the document skill in Codex
~/.agents/skills/document/SKILL.md
$ npx degit archcore-ai/archcore/plugins/archcore/skills/document ~/.agents/skills/documentInstall the document skill in Gemini CLI
~/.gemini/skills/document/SKILL.md
$ npx degit archcore-ai/archcore/plugins/archcore/skills/document ~/.gemini/skills/documentInstall the document skill in Claude.ai
npx degit archcore-ai/archcore/plugins/archcore/skills/document document && zip -r document.zip document # claude.ai → Customize → Skills → + → Create skill → Upload a skill → document.zip
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablearchcore-ai/archcore/plugins/archcore/skills/document is public and reachablegithub.com/archcore-ai/archcore/tree/HEAD/plugins/archcore/s ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-07github.com/archcore-ai/archcore/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/archcore-ai/archcore/blob/HEAD/plugins/archcore/s ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/archcore-ai/archcore/blob/HEAD/plugins/archcore/s ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 223 linesgithub.com/archcore-ai/archcore/blob/HEAD/plugins/archcore/s ↗Pass
SKILL.md
View on GitHub/archcore:document
Record the present state: a technical decision, existing code, or a supplied
research material. Context resolution (skills/_shared/gate-contract.md,
section Context resolution) classifies the request and finds the present owner;
a gate inside the selected track selects the document type. Write affinity: knowledge
types; a filed research and the decision cascade's plan belong to vision.
The standard cascade can add a cpat (experience). A type the user names
explicitly keeps its own category (Named type below).
Command tense: /archcore:plan declares a future canon delta, /archcore:document
records the present state — including work that shipped without a plan — and
/archcore:review reconciles a past declared delta. Claim vocabulary:
skills/_shared/delta-routing.md.
Load skills/_shared/gate-contract.md and skills/_shared/elicitation-contract.md before executing any gate.
Tracks
| Classification | Track and entry | Types the entry gate selects |
|---|---|---|
| decision | skills/_shared/tracks/decision.md, decision.classify |
adr, rfc; rule through the standard cascade; an existing rfc draft on the topic → decision.resolve, which records an adr on an accepted verdict |
| code-doc | skills/_shared/tracks/describe.md, describe.read |
spec, guide, task-type, scenario, doc |
| research material | skills/_shared/tracks/research.md, research.frame |
research, rnd by the closing test; one external material → evidence |
No first word is a mode. When the subject text names a type (skills/_shared/gate-contract.md,
Entry terms) that the selected track produces, the selecting gate treats that type as settled and asks no
type question: record an rfc for gRPC reaches the RFC branch; a leading type
slug takes the Named type path. No track produces a journey; a journey comes
from /archcore:plan or from the named-type path below.
Named type
WHEN the first word of the subject is a kernel document type slug, or the subject writes a slug in
backticks, the named type wins over routing (explicit-type-request-wins.adr).
A slug elsewhere in plain topic text names no type here; inside a track the gate
contract's naming rule still applies. When two slugs qualify, the
first one wins.
- IF a document track produces the named type as its own product, THEN enter that track with the type settled:
adr,rfc→ decision;spec,doc,guide,scenario→ describe;research,rnd,evidence→ research. - IF no document track produces it as its own product —
rule,journey,prd,idea,plan,cpat,task-type,mrd,brd,urd,brs,strs,syrs,srs— THEN compose it directly per the steps below. Arulecomes from the decision track only as a cascade member behind anadr; a namedruleneeds neither. - Apply the compatibility file for the type before the first MCP call that names it.
- Search
.archcore/for a local document of that type on the topic; when one exists, offer to update it instead. - Load
skills/_shared/<type>-contract.mdwhen that file exists, andskills/_shared/precision-rules.md. - WHEN no contract file exists, compose the sections of the
create_documenttemplate for that type. - Create the document with
status: draftthroughcreate_document. - Evaluate relations through
skills/_shared/relation-authoring.md. - WHEN the type's routing condition fails, report it in one result line naming the better-fitting type; ask no question.
Examples of a failed routing condition: a journey where a covering spec
exists (scenario fits), a plan composed without the conductor (it
carries no Declared Delta), or a rule with no adr recording its reason.
When to use
- "We decided to go with microservices" — settled decision
- "Record the decision to use PostgreSQL"
- "Document why we chose JWT over sessions"
- "Make this our team standard for error handling"
- "Draft an RFC for switching from REST to gRPC"
- "Should we switch to Kubernetes?" — open choice: one question offers an
adr, anrfc(resolved into anadrlater), or investigating first - "We accepted the proposal — resolve the RFC" — proposal resolution
- "Document the auth module"
- "Capture how the payment system works"
- "Create reference docs for the config system" — reference material
- "Write a guide for the release process" — how-to instructions
- "Write down how the agent cuts a release" — a repeated agent procedure (
task-type) - "Scenario for checkout over the checkout spec" — a user flow with examples over an existing spec
- "File this benchmark report" — a ready investigation
- "File this vendor PDF as evidence" — one external material
Not document:
- Planning a feature, an initiative, or an intended user journey the request does not name as a
journey→/archcore:plan - Checking documents against code, reviewing branch changes, or a documentation audit →
/archcore:review - First-time setup →
/archcore:init
Routing table
| Signal | Route |
|---|---|
| No arguments, one draft with a state block this command resumes | → resume it |
| No arguments, branch changes or supplied material name a present fact | → a start menu of at most four owners, each with its evidence, the smallest owner first |
| No arguments and no reliable signal | → ask one question: what present fact or subject to record |
| The subject names a document type that no document track produces | → Named type, direct composition |
Decision signals: "we decided", "record this decision", "document why we chose X", "make it our standard", "draft an RFC", a "should we switch to Y" question (the decision track asks which exit). A bare "compare X vs Y" with no proposed target belongs to /archcore:plan's research track; a proposal to add a new capability with no named technical target ("should we add caching?") is feature framing → /archcore:plan |
→ decision track — skills/_shared/tracks/decision.md, entry at decision.classify |
Resolution signals: "resolve the RFC", "we accepted the proposal", "reject the RFC" — an rfc draft exists on the topic |
→ decision track — skills/_shared/tracks/decision.md, entry at decision.resolve |
Code-doc signals: "document the auth module", "capture how the payment system works", reference material (registry, glossary, lookup), how-to instructions, a repeated agent procedure, a user flow with examples over an existing spec |
→ describe track — skills/_shared/tracks/describe.md, entry at describe.read |
| Research-material signals: a supplied investigation report, benchmark, transcript, or vendor document to file as is | → research track — skills/_shared/tracks/research.md, entry at research.frame |
| Unclear | → git investigation, then one classifying question (Step 3) |
Execution
Step 1: Ground
Apply skills/_shared/research-compatibility.md under its condition 1 — a
request or type naming research or evidence, the research track, or a
grounding result of either type. If this skill has no shell tool and no probe
result was supplied, report needs-vocabulary-probe with the helper path and
stop before the first MCP call that names either type.
Before delegating research or evidence work, pass the current vocabulary probe
result and absolute plugin root to the assistant. If the assistant returns
needs-vocabulary-probe, run the helper and resume the same task.
Before delegating any other document write or relation work, pass the absolute
plugin root to the assistant. The assistant reads
skills/_shared/relation-authoring.md under that root.
Apply skills/_shared/actor-subject-compatibility.md under its own condition 1 —
a request whose subject names scenario or journey, or a grounding result of
either type. When that probe returns yes, add scenario and journey to the
type filter below. On older engines, keep the legacy filter; a request to
describe code whose subject names scenario then reports the required version
and exits without a write.
When the probe returns yes, add research and evidence to the type filter
below. On older engines, keep the legacy filter.
Search .archcore/ on the request topic across all three categories — vision,
knowledge, experience. Do not exclude a category from reads. Pass a type filter
matched to this command's moment (adr, rfc, spec, doc, guide, rule,
plus rnd as decision evidence, and research and evidence when the probe returned yes) instead of relying on the global type ranking. When a found document carries
implements, depends_on, or related relations, pull the linked documents one hop across
categories. Duplicate handling lives in the tracks' check-existing gates — do
not resolve duplicates here.
WHEN a found draft on the topic carries an archcore:track state block,
resume it per the resume rules in skills/_shared/gate-contract.md instead of
opening a new track; a block this command does not resume follows resume
rules 8 and 9 there.
If the session root holds no .archcore/, follow
skills/_shared/target-project.md, section Projects without .archcore/: name
the roots the session recap listed, ask which project to use or whether to
initialize the session root, and do not call mcp__archcore__init_project
before the answer. If .archcore/ exists
but contains no documents, proceed on outer-context grounding and report that
zero documents were found.
Global sources. If a mcp__archcore__list_documents /
mcp__archcore__search_documents result has source_kind: "global", load skills/_shared/globals.md. Also load it when a
search_documents response's coverage names a source other than "local" —
even when results is empty: the empty page is exactly where that file's retry
ladder applies. Edit a global document only through its source project, per that
file's write convention, and never join a local and a global document with
add_relation. Absent any global match, proceed as usual.
Step 2: Resolve context
Build the context record per skills/_shared/gate-contract.md, section Context
resolution. IF the subject names a type per Named type above, THEN apply Named
type first. IF accepted canon conflicts with the code the request describes,
THEN report the conflict before any write.
Step 3: Classify
Classify the target as resolution, decision, code-doc, research material, or unclear:
- Resolution — the request names a verdict on an existing open proposal
(resolution signals above) and an
rfcdraft on the topic exists → decision track atdecision.resolve. Check this before Decision: wording that also reads as a settled-decision signal ("we accepted the proposal") routes here whenever a matchingrfcdraft exists. - Decision — the request records a settled choice or an open proposal
(decision signals above) → decision track at
decision.classify, which selectsadr,rfc, or the standard outcome. A type name in the subject (adr,rfc,rule) satisfies that gate'sskip_when. - Code-doc — the request describes existing code, reference material, a
procedure, or a user flow over an existing
spec(code-doc signals above) → describe track atdescribe.read.describe.readrecordsfeatures/*.featurefiles as evidence when present; ascenariowith no coveringspecroutes to the earliest gate that produces thespecperskills/_shared/gate-contract.md. - Research material — the request supplies a ready report or one external
material to file (research-material signals above) → research track at
research.frame; the supplied report satisfies frame inputs without an interview (investigation versus one external material:skills/_shared/gate-contract.md, Entry terms), and the closing test selects the type — a report that ends in a recommendation is anrnd, a report that covers a scope is aresearch. One external material with no investigation entersresearch.gatheras standalone evidence, records the request in the evidence draft's Clarifications, and exits after gather. Follow the compatibility contract's no-write exit when the type is unsupported. - No material — the request asks an unanswered question, including a bare
"compare X and Y" with no proposed target, and supplies
neither a report nor a material → write nothing and name
/archcore:plan <topic>for a new investigation. - Unclear — inspect git state and the working tree first: recent commits and changed files are evidence of what the user has been working on. If the evidence still supports both readings, ask one classifying question — "Is this a decision to record or existing code to document?" — with the recommendation drawn from the git evidence.
Step 4: Execute the track
Run the selected track gate by gate per skills/_shared/gate-contract.md. The
track owns check-existing, per-gate elicitation, composition, and relation
wiring.
Question budget: the ceiling of 5 questions per invocation in
skills/_shared/elicitation-contract.md.
Result
Report the produced documents grouped by category:
- knowledge —
adr,rfc,spec,doc,guide,rule,evidence,scenario - vision —
research(scope-covering report),rnd(recommendation-closed report, or compatibility fallback),plan(architecture cascade) - experience —
task-type(repeated agent procedure),cpat(standard cascade opt-in) - any category — a type composed on the Named type path, with its routing-condition line when one failed
List each document's path and relation edges. Name tracks and steps in plain
words; do not print a gate address of the form <track>.<stage>. Close with one
recommended next action naming only /archcore:plan, /archcore:review, or a
repeat /archcore:document invocation with its subject. WHEN a gate stopped on a
blocking exit check, the next action is the resume command for that draft.
WHEN the run created drafts other than an rfc and no plan covers them, the
next action is /archcore:review, which offers their acceptance. An rfc
resolves through /archcore:document resolve the <rfc title> RFC.
Files in this skill
1document skill questions
How do I install the document skill in Claude Code?
Run npx degit archcore-ai/archcore/plugins/archcore/skills/document ~/.claude/skills/document. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the document skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is the difference between /archcore:plan and /archcore:document?
Use /archcore:plan for planning future features, investigations, or intended user journeys. Use /archcore:document to record the present state, such as settled decisions, existing code, or supplied research.
How can I specify a specific document type?
You can name the document type directly in the subject (e.g., 'record an rfc for gRPC') or use a kernel document type slug as the first word to trigger the named type path.
Can this tool be used to review existing documentation?
No, checking documents against code or performing documentation audits should be done using the /archcore:review command.