A 1,000-page manual can contain the exact answer and still be a terrible prompt.
A larger context window gives the model more room. It does not decide what deserves attention.
Key takeaways
- A larger context window gives the model more room. It does not decide what deserves attention.
- A skill is the operational map over the encyclopedia.
- A well-designed skill makes two separate decisions.
- The skill is the control plane. It should not become the encyclopedia.
- The useful test is not whether the agent had access to the manual. It is whether the right skill activated, selected the right evidence, followed the procedure, and showed its work.
A practical guide to skills, documentation, semantic hierarchy, and retrieval efficiency.
A large documentation corpus passes through a thin skill routing layer and becomes focused evidence.
That is not a criticism of the manual. The source may be accurate, current, and carefully maintained. The failure begins when we hand the whole thing to an AI agent and expect the model to find the right rule, ignore adjacent material, notice version boundaries, choose a procedure, and keep the important evidence in attention while it works.
A larger context window gives the model more room. It does not decide what deserves attention.
This is why a useful skill should not become a miniature encyclopedia. A skill is the operational map over the encyclopedia. It tells the agent when a workflow applies, what to do next, which reference or tool to use, and what evidence must exist before the task is complete.
The durable pattern is simple:
A warning against copying a large manual into SKILL.md, followed by a better path through an index, thin skill, and proof.
- Documentation holds the truth.
- Retrieval selects the evidence.
- The skill directs the work.
- Tools check reality.
What the Agent Skills standard actually gives you
In the open Agent Skills specification, a skill is a directory with a required SKILL.md file. That file starts with YAML frontmatter, including at least a name and description, followed by Markdown instructions. The directory can also contain references, scripts, assets, schemas, templates, and other supporting files.
The useful part is the loading sequence:
- 01The agent sees compact metadata for the available skills.
- 02When a task appears to match, it loads the selected SKILL.md.
- 03The instructions point to individual resources only when the current step needs them.
Why the sequence matters
Anthropic describes this as progressive disclosure. The core workflow stays small while detailed context remains available on demand.
This does not make the result correct. It makes the information path explicit. That is a meaningful improvement because an explicit path can be reviewed, tested, and fixed.
Routing happens twice
A well-designed skill makes two separate decisions.
The first is skill routing: which workflow matches the request?
The name and description are discovery signals. A vague description such as “helps with Ignition” gives an agent little reason to choose that skill over neighboring workflows. A description that names Perspective bindings, property types, tag paths, and validation gives the model a sharper boundary.
The second is resource routing: after the skill activates, which reference, script, schema, or tool does this step require?
An agent debugging an Ignition Perspective binding should not load SQL guidance, alarm design, historian behavior, and HMI styling at the same time. It may need one binding reference, the actual view resource, and a readback check. Everything else can wait.
A task passes through one gate that selects a skill and a second gate that selects the evidence needed for proof.
This is the path:
Task
↓
Select the workflow
↓
Load the skill instructions
↓
Select the reference, script, or tool
↓
Validate with evidenceRouting still needs tests
The path can still fail. A broad description can activate at the wrong time. Two skills can overlap. A reference can be stale or missing. A tool can lack permission. That is why routing needs tests, not confidence.
A loading hierarchy is not an ontology
People often say a skill has a “semantic hierarchy.” That is true only if we use the phrase loosely.
The format gives us a clear loading hierarchy:
It can also support an operational hierarchy:
metadata → workflow instructions → supporting resources
task boundary → procedure → conditional reference → action → validationWhat those layers do
Those layers help an agent move from a broad request to a small set of instructions and evidence.
But the base format does not require an ontology, typed topic system, knowledge graph, or machine-validated workflow model. The Markdown body is flexible. A relationship such as “this policy replaces version 2” exists only if the author states it clearly or another system encodes it.
Structured documentation can carry richer formal semantics than a basic skill. It may use typed topics, stable identifiers, controlled metadata, cross-references, search indexes, retrieval trees, embeddings, or graphs.
So the accurate claim is narrower: a good skill gives an AI agent a compact, runtime-oriented information architecture. It turns relationships that may be implicit in a documentation library into a procedure the agent can follow.
A comparison between the loading hierarchy Agent Skills provides and the formal semantic structures it does not require.
Retrieval efficiency is the real story
Long context capacity and long context use are different problems.
In Lost in the Middle, researchers tested multi-document question answering and key-value retrieval. Models often did better when the relevant material appeared near the beginning or end of the context and worse when it appeared in the middle.
The lesson is not that long context is useless. The lesson is that “the answer exists somewhere in the input” does not guarantee “the model will use the answer reliably.”
Selective retrieval reduces irrelevant material, but selection creates another risk: the system may retrieve the wrong unit.
Size matters. A large passage may include too much unrelated detail. A single sentence may omit the prerequisite, version, or condition that gives the rule meaning. Dense X Retrieval reported better retrieval performance with concise, self-contained proposition-level units than with conventional passages in its experiments.
RAPTOR adds another useful idea. It builds a tree of clustered summaries so retrieval can move between high-level meaning and detailed evidence. That can help with questions that span several sections or levels of abstraction.
None of these studies proves that a SKILL.md file is inherently better than documentation. They study context use and retrieval design. They support the principle beneath a good skill: select the smallest self-contained context that can support the current decision.
Three retrieval units compare a passage that is too large, a fragment that is too thin, and a self-contained unit.
Four layers, four jobs
The strongest design keeps four responsibilities separate.
Four cards separate canonical documentation, indexing, the thin skill, and tools plus proof.
1. Canonical documentation holds the truth.
Manuals, policies, API references, and schemas should remain the maintained source. Copying hundreds of pages into a skill creates a second source that will drift.
2. The information layer makes the source addressable.
Large collections need meaningful topic boundaries, stable headings or IDs, version context, and focused retrieval units. Exact identifiers often benefit from lexical search. Paraphrased questions may benefit from semantic retrieval. Large or complex collections may justify both.
3. The skill directs the workflow.
The skill states when the procedure applies, what to retrieve at each step, which conditions change the path, what the agent must not assume, and what output it should produce.
4. Tools and readbacks check reality.
Scripts handle deterministic operations. Controlled APIs expose current state. Validation, logs, diffs, tests, and readbacks give the agent evidence instead of another opportunity to guess.
The Ignition example
For an Ignition agent, that could mean canonical product documentation for the platform contract, a focused reference for the exact resource type, a skill for the build and validation procedure, and a bounded Gateway tool for discovery and readback.
The skill is the control plane. It should not become the encyclopedia.
What to do with a 1,000-page manual
The practical answer is yes: you do not have to reorganize the manual by hand before you begin. If your AI agent has an internal skill-building tool, attach the document and explicitly tell the agent to use it.
Copy and paste this with the manual attached
Copy-and-paste prompt
Use your internal $skill-creator skill to turn the attached [DOCUMENT NAME] into a production-ready Agent Skill.
Treat the attached document as the source of truth. Create the actual skill files now, not just a summary, outline, or set of recommendations.
Follow the skill-creator standards:
Keep SKILL.md thin. Use it for activation, workflow, routing, safety rules, output requirements, and validation.
Put detailed manual content in focused files under references/. In SKILL.md, state exactly when each reference should be read.
Preserve product version, subsystem, prerequisites, warnings, exceptions, and source page or section references.
If the document covers unrelated tasks or incompatible versions, split it into a small family of focused skills instead of one catchall skill.
Add scripts/ only when repeated deterministic work is safer or more reliable as code.
Test when the skill should activate, when it should not, how it handles missing information, and how it handles version conflicts.
Validate the finished skill package with the validator available in your environment.
When finished, give me:
The location and folder tree of every skill you created.
A short explanation of how each skill routes to its references or scripts.
The test prompts, expected behavior, and actual results.
Any missing, contradictory, outdated, or unreadable source material you found.
If you cannot access the internal $skill-creator skill or cannot read the attached document, tell me before proceeding. Otherwise, build and test the skill now.Why the prompt is direct
It really can be that direct. The first line tells the agent to load its own skill-building standards before it begins. The remaining instructions prevent two common failures: stopping at a summary and stuffing the entire manual into one oversized SKILL.md.
Then give the new skill one real job
Test prompt
Use the new skill to [DESCRIBE A REAL TASK]. Tell me why the skill activated, which reference files it used, and what evidence proves the result.What the test should prove
The useful test is not whether the agent had access to the manual. It is whether the right skill activated, selected the right evidence, followed the procedure, and showed its work.
Skills and documentation solve different problems
Documentation answers: What is true about this system?
A skill answers: For this task, what should the agent do, what should it retrieve, and how should it prove the result?
Retrieval connects them.
Article FAQ
Frequently asked questions
Why can a 1,000-page manual be a terrible prompt?
The failure begins when we hand the whole thing to an AI agent and expect the model to find the right rule, ignore adjacent material, notice version boundaries, choose a procedure, and keep the important evidence in attention while it works.
What does an Agent Skill do?
A skill is the operational map over the encyclopedia. It tells the agent when a workflow applies, what to do next, which reference or tool to use, and what evidence must exist before the task is complete.
What are the two routing decisions in a skill?
The first is skill routing: which workflow matches the request? The second is resource routing: after the skill activates, which reference, script, schema, or tool does this step require?
Should a SKILL.md contain the whole manual?
Keep SKILL.md thin. Use it for activation, workflow, routing, safety rules, output requirements, and validation. Put detailed manual content in focused files under references/.
How do you test a skill made from a manual?
The useful test is not whether the agent had access to the manual. It is whether the right skill activated, selected the right evidence, followed the procedure, and showed its work.
Sources and notes
Documentation referenced
Lifetime membership
Want the toolkit behind this workflow?
The one-time Ignition AI Toolkit membership includes the Web Dev API runner, skill files, setup docs, versioned downloads, and released Ignition 8.3 resources for lifetime members. Founder pricing is available while the first 50 spots last.
Founder lifetime access - $99