Guide · Agent skill
How to use the Importing a Codebase agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The importing-a-codebase skill is an instruction set for an AI agent that is pointed at a project containing source code but no specification documents. The agent reads the project's agent files, docs, manifests and code, then drafts a linked set of spec documents describing what the project should have had. This guide explains what the skill does, how to install it, how to trigger it, and what it depends on so you can decide whether it fits your repository.
Importing a CodebaseJetBrains/thinkrail · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Get the importing-a-codebase ZIP from this page. It contains SKILL.md.
- 2Unzip into a skills folder. Place the folder in ~/.claude/skills/ for personal use, or in the project's .claude/skills/ for one repository. You can also upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Check the prerequisites. Make sure the ThinkRail spec tools and the writing-specs, asking-user-questions, setting-up-a-project and brainstorming skills are available.
- 4Confirm the repo has no specs. Point the agent at an un-specced repository. If specs already exist, the skill hands back to setting-up-a-project instead.
- 5Ask for the spec graph. Make a natural request such as asking for the initial spec graph for this codebase.
- 6Answer the gap questions. Respond to the rounds of questions about purpose, non-goals, unexplained decisions and limitations, or skip them and accept the marked assumptions.
- 7Review in Changes. Check the drafted specs, confirm or correct the inferred content, and approve before anything merges.
What an agent skill is and what this one does
An agent skill is a folder with a SKILL.md file that tells an AI agent how to handle a specific kind of task. The agent loads the instructions when a request matches the skill's description.
This skill covers one job: creating the initial spec graph for an existing codebase. The agent surveys the repo in a set order: agent files such as AGENTS.md and CLAUDE.md first, then docs, manifests, and the top of each candidate module. It then drafts a goal-and-requirements document, an architecture document, and one short spec per genuine module, each linked by id.
- Existing architecture docs, ADRs, glossaries and protocol docs can be adopted into the graph in place, with their content left as written apart from added frontmatter.
- READMEs, CONTRIBUTING files, changelogs, roadmaps, TODOs, implementation plans and generated API docs are treated as input only, not as spec nodes.
- The agent asks only the questions the code cannot answer, such as the reason behind non-obvious decisions, and marks anything it inferred but you have not confirmed.
Install the skill from the ZIP or the Claude apps
Download the ZIP for importing-a-codebase from this page. The package contains a single file, SKILL.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.
In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.
Confirm the prerequisites are present
This skill does not work on its own. It refers to ThinkRail spec tools (spec_grep, spec_graph, spec_create, spec_validate, and edit) and to the writing-specs, asking-user-questions, setting-up-a-project and brainstorming skills from the same package. Those are not included in this file.
If you are not using the ThinkRail toolchain, the instructions will not be usable as a standalone set.
- Confirm the ThinkRail spec tools are available to the agent.
- Confirm the four sibling skills from the same package are installed alongside importing-a-codebase.
Trigger the skill with a natural request
The skill's description says it applies when you ask for the initial spec graph for an existing codebase that has source code but no specs. It is normally reached through setting-up-a-project, so the simplest route is to start that setup flow in an un-specced repo.
You can also ask directly. Requests that match the description include asking the agent to create specs for this existing codebase, or to build a spec graph for a repo that has code but no documentation of its design.
- "Create the initial spec graph for this existing codebase."
- "This repo has code but no specs. Reverse-engineer the specs it should have had."
- "Set up specs for this project, it was never documented."
Answer the agent's questions and review the drafts
Expect the agent to ask in rounds. It asks about the primary job of the project, explicit non-goals, the reasons behind non-obvious decisions, known limitations, and which adoption candidates should become spec nodes. Where it can, it proposes a concrete answer and lets you correct it.
Answers you skip are not blockers. The agent records the assumption in the spec and marks it unconfirmed.
When the agent finishes, it runs spec_validate, then tells you the specs are drafted on the workspace branch. Review them in Changes. Nothing merges until you approve.
- Check every line marked as inferred before approving.
- Look at any drift corrections the agent made to adopted documents.
- Note which candidate docs were adopted and which were left as input.
What people use it for
- Bringing an existing product repo under a spec-driven workflow without writing every spec by hand.
- Onboarding onto an undocumented repository and getting a structured map of its modules and their dependencies.
- Adopting existing architecture docs or ADRs into a ThinkRail spec graph without rewriting their content.
- Capturing known limitations such as missing tests or slow paths in the specs that own them, after you confirm them.
Frequently asked questions
Is the importing-a-codebase skill free to use?
The source file does not state pricing or licensing terms for the skill beyond its Apache-2.0 licence, which is listed for the repository. Check the licence text in the repository for the terms that apply to you.
What do I need to run the importing-a-codebase skill?
You need the ThinkRail spec tools (spec_grep, spec_graph, spec_create, spec_validate, and edit) and the writing-specs, asking-user-questions, setting-up-a-project and brainstorming skills from the same package. The skill does not run scripts and does not use the network, according to its listing.
Where do I install the skill?
Unzip the downloaded folder into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one repository. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
Can I use this skill on a repo that already has specs?
No. The skill tells the agent to stop and hand back to the setting-up-a-project dispatcher if specs already exist, because it is built for un-specced repositories only.
Will the generated specs be accurate?
The specs are inferred from the files and need human review. The skill marks inferred content and states that the output is not confirmed, so approve only after checking it against what the project actually intends.
What are the alternatives if this skill does not fit my workflow?
The source does not name alternatives. If you are not using the ThinkRail toolchain, this skill will not work as a standalone instruction set, so you would need a different approach for documenting your code.
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 this skill if you work in the ThinkRail toolchain and need to bring an existing, un-documented codebase under spec tooling, or if you are onboarding onto a repo and want a structured module map. Skip it if the repository already has specs, if you plan to trust inferred specs without review, or if you are outside the ThinkRail toolchain, since the skill depends on tools and sibling skills that are not included here.
Download the skill