Key Takeaways
- An Agent Skill is a reusable folder that gives an AI agent task-specific instructions, scripts, and supporting files.
- The required file is usually
SKILL.md, which defines what the skill does and when the agent should use it. scripts/should contain executable logic, such as Python, JavaScript, Bash, validation tools, or data processing steps.resources/orreferences/should contain knowledge files, policies, examples, schemas, and documentation.assets/should contain reusable static files, such as templates, brand files, sample data, diagrams, and output formats.
What is an Agent Skill Folder?
An Agent Skill folder is a self-contained package of knowledge and workflow logic that an AI agent can discover, load, and use when a task requires it. At minimum, the folder contains a SKILL.md file. This file gives the agent the skill name, description, usage rules, and task instructions. The open Agent Skills specification describes this as a progressive structure where metadata is loaded first, the main instruction file is loaded when relevant, and deeper files are loaded only when needed.
In plain terms, the skill folder works like a playbook for an AI agent.
Instead of giving the agent a long prompt every time, the enterprise team stores the workflow once. The agent can then reuse it across tasks, teams, and systems.
For example, a manufacturing AI agent may use different skills for:
- Creating production downtime reports
- Validating MES data
- Summarizing machine maintenance logs
- Mapping shop-floor alerts to business impact
- Generating executive KPI briefs
- Checking compliance against internal SOPs
Each skill should have its own folder. This keeps the agent modular and reduces prompt overload.
Why Folder Structure Matters for Enterprise AI Agents
A weak skill folder structure creates confusion. The agent may read too much, load the wrong files, run the wrong script, or mix business logic with reference material.
A strong folder structure creates operating leverage. It gives AI teams a repeatable model for scaling agent capabilities without rebuilding every workflow from scratch.
For enterprise AI, the folder structure affects five areas.
- First, it improves reliability. The agent knows where to find instructions, code, examples, and templates.
- Second, it improves governance. Teams can review files by function. Legal can review policy references. Engineering can review scripts. Brand teams can review assets.
- Third, it improves security. Sensitive files can be isolated, permissioned, or excluded from agent access.
- Fourth, it improves maintainability. When the SOP changes, the team updates the right file instead of editing a long system prompt.
- Fifth, it improves scalability. Teams can build many skills using the same structure, naming rules, and review process.
Core Agent Skill Folder Structure
A practical enterprise folder structure should separate role, logic, knowledge, and outputs.
filename.md
skill-name/
├── SKILL.md
├── scripts/
│ ├── validate_input.py
│ ├── transform_data.py
│ └── generate_report.py
├── resources/
│ ├── business_rules.md
│ ├── data_schema.json
│ └── terminology.md
├── references/
│ ├── sop-production-reporting.md
│ └── compliance-policy.md
├── assets/
│ ├── report-template.docx
│ ├── dashboard-layout.png
│ └── brand-guidelines.pdf
├── examples/
│ ├── sample-input.json
│ └── sample-output.md
├── tests/
│ ├── test_cases.md
│ └── expected_outputs/
└── README.mdThis structure gives each file a clear job. It also helps human teams audit the skill before it moves into production.
The most important rule is simple: do not put everything in SKILL.md.
SKILL.md should guide the agent. It should not become a large knowledge dump. The Agent Skills specification recommends keeping the main skill file concise and moving deeper files into folders such as scripts/, references/, or assets/.
How to Use the scripts/ Folder
The scripts/ folder contains executable logic. These files help the agent perform tasks that need precision, repeatability, or computation.
Use scripts/ for:
- Data cleaning
- File conversion
- Input validation
- API calls
- Calculations
- Report generation
- Testing helpers
- Workflow automation
For example:
filename.md
scripts/
├── validate_csv.py
├── calculate_oee_loss.py
├── clean_sensor_logs.py
├── generate_summary.py
└── export_to_docx.pyThe main benefit is control. Instead of asking the agent to “figure out” calculations through natural language, the skill gives it tested code.
This matters in enterprise AI because many workflows involve structured data. An agent that analyzes production logs, sales pipeline data, inventory variance, or compliance records needs deterministic logic in key steps.
Scripts also reduce hallucination risk. The agent can call a script for a calculation instead of guessing.
A good script file should include:
- Clear function names
- Input and output format
- Error handling
- Logging
- Safe defaults
- No hardcoded credentials
- Version notes
Avoid placing business policy inside scripts unless the policy needs to be enforced through code. Keep business rules in resources/ or references/, then let scripts apply them.
How to Use the resources/ Folder
The resources/ folder stores task-specific knowledge that the agent may need during execution. This is where you place structured business context.
Use resources/ for:
- Data schemas
- Taxonomies
- Glossaries
- Product rules
- Process maps
- Decision trees
- KPI definitions
- Prompt fragments
- Role-specific guidance
Example:
filename.md
resources/
├── kpi-definitions.md
├── downtime-code-map.csv
├── mes-data-schema.json
├── report-style-guide.md
└── business-rule-matrix.mdFor an enterprise AI solution provider, this folder is critical because it connects the agent to company-specific knowledge.
For example, a generic AI model may know what OEE means. But it may not know how your company defines planned downtime, minor stoppage, speed loss, rework, or scrap. Those definitions belong in resources/.
This structure also supports private knowledge base design. Instead of relying only on model memory, the agent can load approved reference material from controlled files.
Best practice: keep resources modular. Do not create one massive file. Split the files by business concept, data type, or workflow step.
resources/ vs references/: What Is the Difference?
Some teams use only resources/. Others separate resources/ and references/.
Here is a practical distinction:
| Folder | Purpose | Example |
|---|---|---|
|
resources/ |
Operational files the agent uses during the task |
Schema, glossary, code map, KPI rules |
|
references/ |
Longer background documents the agent may consult |
SOPs, policies, manuals, research, compliance docs |
|
assets/ |
Static files used in output creation |
Templates, images, brand files, sample layouts |
|
scripts/ |
Executable task logic |
Python, JavaScript, Bash scripts |
Use references/ when the file is long, policy-heavy, or used for background context. Use resources/ when the file directly shapes execution.
For example, a resources/data_schema.json file tells the agent how to parse data. A references/data-governance-policy.md file tells the agent what rules apply when handling that data.
This distinction keeps the skill easier to audit.
How to Use the assets/ Folder
The assets/ folder contains static files that support the final output or user experience.
Use assets/ for:
- Report templates
- Slide templates
- Email templates
- Brand guidelines
- Icons
- Diagrams
- Screenshots
- Example visuals
- Document layouts
- Sample files
Example:
filename.md
assets/
├── executive-report-template.md
├── board-slide-layout.pptx
├── brand-tone-guide.pdf
├── chart-style-reference.png
└── output-format-example.docxIn enterprise workflows, output format matters. A CFO may need a one-page summary. A plant manager may need a root cause table. A CEO may need a board-level slide. The assets/ folder lets the agent produce these outputs in the right format.
This is especially useful for branded workflows. For example, a marketing AI agent can use approved tone guidelines, landing page templates, and content briefs. A sales enablement agent can use approved proposal templates and case study formats.
The rule: assets should support output quality, not replace instructions. The agent should read SKILL.md first, then use assets only when needed.
Add an examples/ Folder for Better Output Quality
The examples/ folder is not always required, but it improves consistency.
Use it for:
- Sample inputs
- Sample outputs
- Before-and-after examples
- Edge cases
- Bad examples
- Ideal format references
Example:
filename.md
examples/
├── sample-input-maintenance-log.csv
├── sample-output-executive-summary.md
├── bad-output-example.md
└── edge-case-missing-data.mdAdd a tests/ Folder Before Production Use
Enterprise teams should not treat skills as casual prompt folders. If a skill affects reporting, customer communication, compliance, or operational decisions, it needs testing.
Use tests/ for:
- Test cases
- Expected outputs
- Input validation scenarios
- Failure modes
- Security checks
- Regression tests
Example:
filename.md
tests/
├── test_cases.md
├── expected_output_case_01.md
├── expected_output_case_02.md
└── failure_modes.mdA good test case should include:
- User request
- Input file
- Expected skill behavior
- Files the agent should access
- Files the agent should not access
- Expected output format
- Failure conditions
This is where enterprise AI governance becomes practical. You do not only define rules. You test whether the agent follows them.
Example: Manufacturing Agent Skill Folder
A manufacturing AI agent skill may look like this:
filename.md
manufacturing-downtime-root-cause/
├── SKILL.md
├── scripts/
│ ├── parse_machine_logs.py
│ ├── calculate_downtime_minutes.py
│ └── detect_recurring_faults.py
├── resources/
│ ├── downtime-code-map.csv
│ ├── machine-taxonomy.json
│ └── oee-formulas.md
├── references/
│ ├── maintenance-sop.md
│ └── production-reporting-policy.md
├── assets/
│ ├── plant-manager-report-template.md
│ └── executive-summary-template.md
├── examples/
│ ├── sample-log.csv
│ └── sample-report.md
└── tests/
├── missing-data-test.md
└── abnormal-downtime-test.mdThis structure supports operational reliability. It also lets the enterprise connect AI agents with MES, CMMS, IIoT, and production data workflows.
Conclusion
A strong Agent Skill folder structure turns AI agents from general assistants into repeatable enterprise operators. The core pattern is simple: use SKILL.md for instructions, scripts/ for executable logic, resources/ for operational knowledge, references/ for deeper documentation, and assets/ for reusable output files.
For enterprise AI teams, this structure supports scalability, governance, security, and better output quality. It also reduces prompt duplication and helps agents work with approved business context.
The best approach is to treat each skill as a managed capability package. Keep it modular. Test it. Version it. Assign ownership. Then connect it to real business workflows where repeatability and control matter.
Done well, Agent Skills become a foundation layer for enterprise AI adoption. They help companies move from one-off AI use cases to governed, reusable agent workflows.
FAQs
What is the minimum Agent Skill folder structure?
The minimum structure is one folder with a SKILL.md file. This file defines the skill name, description, and instructions. For enterprise use, teams should also add folders such as scripts/, resources/, assets/, examples/, and tests/.
What should go inside the scripts/ folder?
The scripts/ folder should contain executable files that help the agent perform repeatable tasks. Common examples include data validation, file conversion, calculations, API calls, report generation, and automation steps.
What is the difference between resources/ and assets/?
resources/ contains knowledge the agent uses to complete the task, such as schemas, rules, glossaries, and decision trees. assets/ contains static files used for output, such as templates, images, slide layouts, brand files, and sample documents.
Turn Enterprise Knowledge Into Autonomous AI Agents
Your Knowledge, Your Agents, Your Control
Your Knowledge, Your Agents, Your Control
Related Articles
Latest Articles
