Guide · Agent skill
How to use the Documentation & Modernization agent skill (doc-and-modernize)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The doc-and-modernize skill is a set of instructions that an AI agent (such as Claude or GitHub Copilot) loads so it can do two jobs on a repository you have cloned locally: write one cited architecture document for onboarding, and turn that document into a phased plan for modernizing, migrating or rewriting an older system. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what it needs and touches. By the end you will be able to run a documentation pass and, if needed, a modernization plan on your own checkout.
Documentation & Modernizationgithub/awesome-copilot · MIT Download the skill Quick start
- 1Download the ZIP. Download the doc-and-modernize ZIP from this page.
- 2Unzip into a skills folder. Unzip into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
- 3Check out the repository locally. Make sure the repository you want documented is cloned on disk and the branch you care about is checked out.
- 4Ask for the architecture document. Request something like "write up the architecture" or "create an onboarding doc" from inside the repository.
- 5Review the output. Check the remote, branch and commit it records, the file citations, and any [UNVERIFIED] markers before sharing.
- 6Ask for a modernization plan if needed. For "modernize this" or "plan the migration", the skill builds the architecture document first if none exists, then writes the phased plan.
What the skill makes the agent do
The skill has two modes. Documentation mode reads the files in your local checkout and writes a single architecture document. Each claim in it is tied to specific files, and the document records the remote, branch and commit it describes, so a reader can tell which snapshot it covers. It is meant to be a reference a new engineer can read on their first week.
Modernization mode is for requests to modernize, migrate, upgrade or rewrite a legacy system. If no architecture document exists yet, the agent builds one first, in the same pass, and then writes a phased plan. The plan uses a safety ladder and a time-boxed feasibility check, so it does not require a fully passing legacy test pipeline before work can start.
- Documentation mode: one Markdown architecture document, with a tech-stack table, entry points, a commands inventory, directory layout, deployment and runtime versions, and an end-of-life dependency scan.
- Modernization mode: a phased plan built on that document, plus a copilot-instructions template that encodes the canonical commands and phase-gating rules.
- Migration hazard catalog: a stack-agnostic list of hazards the plan is checked against before implementation.
Install the skill from the ZIP
Download the ZIP for doc-and-modernize from this page. Then choose one of the two options below. The skill folder contains SKILL.md, plus references/copilot-instructions.template.md and references/migration-hazards.md.
For a personal install, unzip the folder into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so it applies only to that repository. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your repository
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with a natural request
You do not need a special command. Describe what you want in plain language from inside the repository you have checked out. The skill's description lists phrases that route to each mode, so wording like the examples below is enough.
For documentation, ask things such as "write up the architecture", "document how this codebase works" or "create an onboarding doc". For modernization, ask "modernize this", "plan the migration" or "how do we get off this legacy stack". If you only want the architecture document, say so; the skill otherwise runs straight through to a plan.
- Works best when the agent is working in the local clone you want documented.
- Ask for documentation first if you are unsure; the skill describes it as the evidence base for any later modernization plan.
What the skill needs
The skill needs git, because it runs git commands to read the remote URL, current branch and latest commit of your checkout. It also needs a locally cloned copy of the repository, since it reads files on disk. Network or GitHub API access is optional and is used only as a flagged last-resort fallback for facts that cannot be found in the code, such as whether a CI check is a required status check.
The skill does not run scripts, according to its listing. It does use the network in that optional fallback case.
- git installed and available to the agent
- A local clone of the repository to analyze
- Optional network access, used only for facts that cannot be found on disk and are marked as such in the output
git remote -v
git branch --show-current
git log -1Safety notes: scripts, network and credentials
The skill is local-first. It reads files on disk by default and only looks online for facts it cannot find in the code. Any remote-sourced fact is labelled in the document (for example [UNVERIFIED]) so you can see it did not come from the checkout.
Remote URLs can contain embedded tokens. The skill is written to redact credentials from remote URLs before recording them. The skill's own notes still say you should review the output before sharing it, because a repository may contain other sensitive material.
- Runs scripts: no
- Uses network: yes, only as a flagged last-resort fallback
- Review generated documents for secrets before sharing them outside your team
Tips for better results
Give the agent the right checkout. The document describes exactly the code on disk, not the main branch on GitHub, so check out the branch you care about first.
Read the marked gaps. Items marked [UNVERIFIED] or listed as out of scope are things the skill chose not to guess. Confirm them with the team rather than treating them as facts.
Keep the architecture document as the reference. The modernization plan cites it, so a stale or wrong document will weaken the plan.
- Check out the branch and commit you want described before you start.
- Expect remote-only facts such as CI run history and sibling repositories to be out of scope or unverified.
- Use the copilot-instructions template only after you tune its commands and gates to your project.
What people use it for
- Onboarding a new engineer with a written architecture reference that cites files and a specific commit.
- Planning a migration of an older system, starting from an evidence-based architecture document.
- Listing the canonical build, test and lint commands of an unfamiliar project, checked against its manifests and CI config.
- Finding end-of-life or unmaintained frameworks and base images before a runtime upgrade.
- Generating a copilot-instructions starting file that encodes the project's commands and phase-gating rules.
Frequently asked questions
Is the doc-and-modernize skill free?
The source gives the licence as MIT, which is shown on this page. It does not state any price, so check the licence text for the terms that apply to you.
What do I need to install doc-and-modernize?
You need the skill ZIP from this page, an agent that supports skills, and git on your machine. You also need a local clone of the repository you want documented.
Where do I put the skill files?
Unzip them into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one repository. In the Claude apps you can instead upload it under Settings → Capabilities → Skills.
Does the skill need internet access?
Not for the core work. It reads files on disk and runs git commands. Network or GitHub API access is an optional last-resort fallback for facts that cannot be found in the code, and those results are flagged.
Does the skill run scripts on my machine?
According to its listing, no. It reads files and runs git commands to record the branch and commit.
When should I use a different tool instead?
The skill is not suited to projects you have not cloned locally, since it depends on reading files on disk. It is also heavier than needed for a quick question about a single file.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use doc-and-modernize if you are onboarding onto an unfamiliar codebase, or planning a migration of an older system, and you want a written reference tied to a specific commit. Skip it for quick questions about one file, for repositories you have not cloned, or for projects where you cannot review generated output for sensitive material before sharing.
Download the skill