Skills are modular knowledge packages that enhance agent capabilities without code changes. They follow the open Agent Skills specification and contain domain-specific instructions, conventions, and reference material that agents load on demand.
- What are skills?
- Quick start
- SKILL.md format
- Skill directory structure
- Skill placement
- Agent configuration
- How skills load
- Agent skill tool
- Best practices
- Complete example
Skills are instructional markdown files that teach agents domain knowledge. Unlike tools (which execute actions), skills provide context that shapes how an agent thinks and responds.
| Aspect | Skills | Tools |
|---|---|---|
| Purpose | Provide knowledge and context | Execute actions |
| Format | Markdown with YAML frontmatter | Executable code or API |
| Loading | On demand or auto-loaded into prompt | Called dynamically by agent |
| Scope | Reasoning, planning, conventions | Runtime execution |
Good candidates for skills:
- Git workflow conventions and commit practices
- Code review criteria and standards
- Project-specific naming conventions
- Testing strategies and patterns
- Security best practices for your domain
- Documentation writing guidelines
Create your first skill in 30 seconds:
# 1. Create the skill directory
mkdir -p ~/.botnexus/skills/git-workflow
# 2. Write the SKILL.md file
cat > ~/.botnexus/skills/git-workflow/SKILL.md << 'EOF'
---
name: git-workflow
description: "Git conventions: commit format, branch naming, and PR process"
---
# Git workflow
Use conventional commits with imperative mood:
- `feat: add user search endpoint`
- `fix: prevent null reference in parser`
- `docs: update skills guide`
Always run `dotnet test` before committing.
EOFThe skill is now discoverable. Agents can list it with the skills tool and load it when they need git guidance.
Every skill requires a SKILL.md file containing YAML frontmatter and a markdown body.
| Field | Required | Constraints | Description |
|---|---|---|---|
name |
Yes | Max 64 chars. Lowercase a-z, digits, hyphens. No leading/trailing/consecutive hyphens. Must match directory name. |
Unique skill identifier. |
description |
Yes | 1–1024 chars, non-empty. | What the skill does and when to use it. Include keywords that help agents find it. |
license |
No | — | License name or reference to a bundled license file. |
compatibility |
No | 1–500 chars if provided. | Environment requirements (intended product, system packages, network access). |
metadata |
No | String key → string value map. | Arbitrary key-value data for client-specific extensions. |
allowed-tools |
No | Space-delimited tool names. | Pre-approved tools the skill may use. Experimental — support varies by agent. |
disable-model-invocation |
No | Boolean. Default false. |
BotNexus extension. When true, the skill is excluded from model context (used for agent-internal skills). |
---
name: code-review
description: "Code review checklist and approval criteria for pull requests"
license: MIT
compatibility: "Requires access to GitHub API"
metadata:
team: platform
priority: high
allowed-tools: gh git
---The markdown body after frontmatter contains the skill instructions. Write whatever helps agents perform the task. Recommended content:
- Step-by-step instructions
- Concrete examples of inputs and outputs
- Common edge cases and how to handle them
The agent loads the entire body when it activates a skill. For large skills, move detailed content into reference files.
A skill is a directory containing a SKILL.md and optional supporting files, per the Agent Skills spec:
my-skill/
├── SKILL.md # Required — metadata + instructions
├── scripts/ # Optional — executable code agents can run
├── references/ # Optional — detailed docs loaded on demand
└── assets/ # Optional — templates, schemas, data files
Executable code that agents can run. Scripts should be self-contained, include helpful error messages, and handle edge cases. Supported languages depend on the agent implementation.
Additional documentation loaded when needed. Keep individual files focused — agents load these on demand, so smaller files mean less context usage.
references/
├── REFERENCE.md # Detailed technical reference
├── api-patterns.md # API-specific guidance
└── error-codes.md # Error handling lookup
Static resources like templates, schemas, lookup tables, and example files.
BotNexus discovers skills from three locations, scanned in priority order:
Available to all agents. Stored in ~/.botnexus/skills/.
~/.botnexus/skills/
├── git-workflow/SKILL.md
├── testing-standards/SKILL.md
└── security-checklist/SKILL.md
Use global skills for team-wide standards, shared conventions, and reusable best practices.
Global skills are visible to every agent, so editing one changes all-agent behaviour. The
skill_managetool can write here by default when the request usesscope: shared; setAllowSharedSkillManagementtofalseto make this scope read-only. Deletion also needsAllowSkillDeletion.
Available only to a specific agent. Stored in ~/.botnexus/agents/{agent-id}/skills/.
~/.botnexus/agents/code-reviewer/skills/
├── review-criteria/SKILL.md
└── approval-process/SKILL.md
Use per-agent skills for role-specific knowledge, custom methodologies, and domain expertise unique to that agent.
Scoped to a project workspace. Stored in {workspace}/skills/.
my-project/skills/
├── project-conventions/SKILL.md
└── deploy-process/SKILL.md
Use workspace skills for project-specific conventions that travel with the codebase.
Linked skill folders and linked parent directories are blocked by default. To use a separate
repository as the live source of a skill, enable allowSymlinkedSkills through the CLI.
See Allow skills linked from another repository
for enable/disable commands, per-agent overrides, and security limits.
When multiple locations define a skill with the same name, higher-priority sources override lower ones:
Workspace (highest) → Per-agent → Global (lowest)
For example, if both ~/.botnexus/skills/security/SKILL.md and my-project/skills/security/SKILL.md exist, the workspace version is used.
Configure skills per-agent in ~/.botnexus/config.json under agents.{agent-id}.skills. As
everywhere else, config.json is a flat top-level document with camelCase keys and no
BotNexus wrapper — see
Canonical document shape and location:
{
"agents": {
"code-reviewer": {
"provider": "copilot",
"model": "gpt-4.1",
"skills": {
"enabled": true,
"autoLoad": ["git-workflow", "review-criteria"],
"disabled": ["experimental-skill"],
"allowed": ["git-workflow", "review-criteria", "testing-standards"],
"maxLoadedSkills": 20,
"maxSkillContentChars": 100000
}
}
}
}| Field | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | true |
Master switch. When false, the skills system is completely disabled for this agent. |
autoLoad |
string[] | null |
Skill names to load automatically at session start. These are injected into the prompt without the agent requesting them. |
disabled |
string[] | null |
Skill names explicitly denied. These are never loaded, regardless of other settings. Uses exact name matching — no wildcards. |
allowed |
string[] | null |
Allowlist of skill names. When set, only these skills can load. When null, all discovered skills are allowed. |
maxLoadedSkills |
int | 20 |
Maximum number of skills that can be loaded simultaneously into the prompt. |
maxSkillContentChars |
int | 100000 |
Maximum total characters of skill content in the prompt. Prevents context window exhaustion. |
The resolver applies filters in this order:
- If
disabledcontains the skill name → denied (always wins) - If
allowedis set and does not contain the skill name → denied - Otherwise → eligible for loading
A skill is only loaded if it is in autoLoad or explicitly loaded by the agent at runtime. Eligible skills that aren't auto-loaded appear in the "available" list.
Note: The
disabledandallowedlists use exact name matching only. Wildcard patterns are not supported.
The full pipeline from disk to agent prompt:
┌─────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Discovery │ → │ Validation │ → │ Resolver │ → │ Prompt injection │
│ 3-path scan │ │ name, desc, │ │ allow/deny, │ │ active + available │
│ + merge │ │ format checks │ │ autoLoad, │ │ sections │
│ │ │ │ │ budget limits │ │ │
└─────────────┘ └──────────────┘ └──────────────┘ └──────────────────┘
SkillDiscovery scans three directories for subdirectories containing SKILL.md:
~/.botnexus/skills/(global)~/.botnexus/agents/{agent-id}/skills/(per-agent){workspace}/skills/(workspace)
Same-named skills from higher-priority sources override lower ones.
Each skill is validated before inclusion:
- Name must match the directory name exactly, be 1–64 lowercase alphanumeric characters with hyphens, and contain no consecutive hyphens (
--). - Description must be non-empty and at most 1024 characters.
- Compatibility, if provided, must be at most 500 characters.
- Skills with
disable-model-invocation: trueare excluded from model context.
Skills that fail validation are silently skipped.
SkillResolver applies the agent's SkillsConfig to determine which skills to load:
- Skills in
disabledare denied. - If
allowedis set, skills not in the list are denied. - Among eligible skills, those in
autoLoador explicitly loaded by the agent are activated. - Loading stops when
maxLoadedSkillsormaxSkillContentCharsis reached.0blocks non-empty requests for that budget; a negative value means unlimited.
The resolver produces loaded, available (eligible but not loaded), and denied lists. It also records a structured rejection for each requested skill refused by the count or content budget. Each rejection includes the configured limit, current usage, and requested increment.
SkillPromptBuilder generates a prompt section wrapped in sentinel markers:
<!-- SKILLS_CONTEXT -->
## Active Skills
The following skills are loaded and active:
- **git-workflow**: Git conventions: commit format, branch naming, and PR process
## Skill: git-workflow
[full skill content here]
## Skills Available (not loaded)
Use the `skills` tool with action `load` to activate a skill when needed.
- **testing-standards**: Unit and integration testing patterns
<!-- END_SKILLS_CONTEXT -->
Skill content is sanitized to strip sentinel markers, preventing prompt injection.
Agents interact with skills through the skills tool, which supports two actions.
The agent calls the skills tool with action: "list" to see what's available:
Agent: I need to check what skills are available.
→ Tool call: skills { "action": "list" }
← Tool response:
## Loaded Skills
- **git-workflow**: Git conventions: commit format, branch naming, and PR process
## Available Skills (not loaded)
Use `skills` tool with action `load` and the skill name to activate.
- **testing-standards**: Unit and integration testing patterns
- **security-checklist**: Security review checklist for PRs
The agent calls the skills tool with action: "load" and skillName to activate a skill:
Agent: I need testing guidance for this PR.
→ Tool call: skills { "action": "load", "skillName": "testing-standards" }
← Tool response:
## Skill: testing-standards
# Testing standards
Write unit tests for all public methods...
[full skill content]
Once loaded, the skill content is available in the agent's context for the rest of the session.
- Skill not found:
Skill 'unknown-skill' not found. Use action 'list' to see available skills. - Already loaded:
Skill 'git-workflow' is already loaded. - Denied by config:
Skill 'experimental' is not available for this agent.The response does not expose the denied skill's path or content. - Count budget exceeded: the response includes
reason=count_limitand the configured, current, and requested skill counts. - Content budget exceeded: the response includes
reason=content_limitand the configured, current, and requested character counts.
A budget refusal does not include the skill body and does not raise either budget. If discovery found authorized support files under references/, templates/, scripts/, or assets/, the response names the resolved root tier and lists those relative paths. The agent can then use view_file to load one bounded support file. A denied skill remains unreadable through view_file; a missing skill or support file is reported separately.
One skill = one domain. Avoid bloated multi-purpose skills.
✅ Good: git-workflow, testing-strategy, security-checklist
❌ Bad: general-knowledge, everything-you-need
Agents are LLMs that benefit from explicit, structured content:
- Use clear step-by-step instructions
- Organize with descriptive headings
- Include concrete, copy-pasteable examples
- Prefer lists over dense paragraphs
The description field helps agents decide when to load a skill. Include keywords that match likely tasks:
description: "Git conventions: commit format, branch naming, PR process, merge strategy"Per the Agent Skills spec, keep the main SKILL.md concise. Move detailed reference material to references/ files that agents load on demand:
See [the API reference](references/api-patterns.md) for detailed endpoint documentation.Split large skills into a concise SKILL.md (overview + key instructions) and reference files (detailed lookups, tables, examples):
my-skill/
├── SKILL.md # ~200 lines: overview + core instructions
└── references/
├── error-codes.md # Loaded only when agent needs error details
└── migration-guide.md # Loaded only during migration tasks
Skill directory names must match the name field and should clearly indicate purpose:
✅ Good: code-review-criteria, git-workflow, security-checklist
❌ Bad: skill1, my-knowledge, temp
A production-ready skill with frontmatter, content, and a references directory.
~/.botnexus/agents/code-reviewer/skills/review-standards/
├── SKILL.md
└── references/
└── checklist-details.md
---
name: review-standards
description: "Code review checklist, approval criteria, and common issues for pull requests"
license: MIT
metadata:
team: platform
---
# Review standards
Apply this checklist when reviewing pull requests.
## Quick checklist
1. **Correctness** — Does the code do what the PR description says?
2. **Tests** — Are new paths covered by unit tests?
3. **Style** — Does it follow project conventions?
4. **Security** — No hardcoded secrets, proper input validation?
5. **Performance** — No obvious regressions (N+1 queries, unbounded loops)?
6. **Docs** — API changes documented? README updated?
## Approval criteria
Approve when all checklist items are addressed (or marked N/A), tests pass, and no blocking issues remain.
## Common issues to flag
- Missing error handling for external calls
- Inconsistent naming or style
- Breaking API changes without migration path
- Insufficient test coverage for edge cases
See [detailed checklist](references/checklist-details.md) for expanded criteria.# Detailed review checklist
## Functionality
- [ ] Code implements the described feature or fix
- [ ] Logic handles edge cases (nulls, empty collections, boundary values)
- [ ] Changes don't break existing behavior
## Testing
- [ ] Unit tests for new public methods
- [ ] Test names describe what they verify
- [ ] Edge cases have dedicated tests
- [ ] All tests pass locally with `dotnet test`
## Security
- [ ] No hardcoded secrets or credentials
- [ ] Input validation on all external data
- [ ] No SQL injection or path traversal vulnerabilities
- [ ] Secure defaults used throughout- Agent Skills specification — the open standard for SKILL.md format
- Configuration guide — full
config.jsonreference including agent settings - Architecture overview — how skills fit into the BotNexus pipeline