Agent Skills

Skills are packages of procedural knowledge that agents load on demand. They follow the Agent Skills open standard and work across multiple AI agents.

Installing Built-in Skills

When you initialize a toolchain, Nia installs only the embedded skills required by tools configured with method = "skill":

nia config init --issues github_issues --code github
# Installs .agents/skills/issue-read-github/
#          .agents/skills/pr-read-github/

To export the complete embedded library, run:

nia config export --skills

Explicit export writes all 18 embedded skills. Existing files are preserved unless you add --force. Custom skills are not generated by this command; create their directories and SKILL.md files yourself.

Embedded Skill Library

Local issue, ticket, and code tools use method = "local"; they do not require or export skill packages during initialization.

Skill Structure

Each skill is a directory containing:

skill-name/
├── SKILL.md          # Required: metadata and instructions
└── references/       # Optional: additional documentation

SKILL.md Format

The SKILL.md file has two parts:

Frontmatter (YAML)

---
name: issue-read-github
description: >
  Retrieves and reads issues from GitHub issue trackers using gh CLI.
  Use when working with GitHub issues, or when the user mentions reading,
  viewing, or retrieving issues from GitHub.
version: "1.0.0"
---

Body (Markdown)

The body contains instructions the agent follows. Write in imperative language:

# GitHub Issue Retrieval

## Prerequisites
- gh CLI installed and authenticated

## Basic Commands

### List Issues
\`\`\`bash
gh issue list
gh issue list --state closed
\`\`\`

### View Issue Details
\`\`\`bash
gh issue view <number>
\`\`\`

## Best Practices
1. Check comments for updates
2. Review linked PRs
3. Consider issue labels and assignees

Customizing Skills

Edit Existing Skills

1. Locate the skill: .agents/skills/<skill-name>/SKILL.md
2. Edit the body to match your team’s practices
3. Commit to version control to share with your team

Example customization:

# GitHub Issue Retrieval

## Prerequisites
- gh CLI installed and authenticated
- VPN connected to company network

## Our Team Practices
- Always check #engineering Slack for context
- Label issues with `team:backend` or `team:frontend`
- Mention relevant RFC documents in issue comments

## Basic Commands
...

Add Progressive Disclosure

For detailed documentation that shouldn’t always be loaded:

1. Create references/ subdirectory
2. Add Markdown files with detailed content
3. Reference from main SKILL.md: “See references/advanced-queries.md for complex JQL patterns”

Example:

.agents/skills/issue-read-jira/
├── SKILL.md
└── references/
    ├── jql-syntax.md
    ├── custom-fields.md
    └── workflow-states.md

Then in SKILL.md:

## Advanced Queries

For complex JQL patterns and custom field queries, see `references/jql-syntax.md`.

Custom Skill Names

For custom tools, optionally specify a skill name and reference it from the description:

[issue_tracker]
name = "acme_tracker"
type = "custom"
method = "skill"
skill_name = "acme-issue-read"
description = "Use the {{skill_name}} skill to read ACME issues."

Then create .agents/skills/acme-issue-read/SKILL.md with your custom instructions. During prompt composition, Nia replaces {{skill_name}} with acme-issue-read. If skill_name is omitted, it defaults to the custom tool’s exact name (acme_tracker in this example). The field is used only when method = "skill".

Naming Conventions

Skill names should follow the pattern: {category}-{action}-{variant}

Valid examples:

• issue-read-github
• pr-read-bitbucket
• acme-deploy-prod
• custom-build-docker

Invalid examples:

• GithubIssues (use kebab-case, not PascalCase)
• read_issues (use hyphens, not underscores)
• issue (missing action and variant)

Reserved prefixes (for built-in skills):

• issue- - Issue tracker operations
• pr- - Pull request operations
• ticket- - Ticket tracker operations
• scanner- - Security scanner operations

Custom skills using reserved prefixes will trigger a warning but are allowed.

Skill Scope

Skills can be stored at two levels:

Project Scope

• Location: <repo>/.agents/skills/
• Committed to version control
• Shared with team members
• Project-specific customizations

Best for:

• Team-wide practices and conventions
• Project-specific tool configurations
• Shared knowledge and procedures

User Scope

• Location: ~/.agents/skills/
• Not committed (personal)
• Available across all projects
• Personal preferences and customizations

Best for:

• Personal shortcuts and preferences
• Company-wide standards across projects
• Tools you use in all projects

Automatic Detection

When you run nia config export --skills, the scope is auto-detected:

Override with –scope

# Force project scope (version-controlled)
nia config export --skills --scope=project

# Force user scope (global, personal)
nia config export --skills --scope=user

Scope Precedence

When an agent loads skills, it checks locations in order:

1. Project: .agents/skills/ (highest priority)
2. User: ~/.agents/skills/

Project skills take precedence over user skills with the same name.

Cross-Agent Compatibility

Skills work across:

• GitHub Copilot - Full support for Agent Skills standard
• Claude Code - Compatible skill loading
• OpenCode - Follows same discovery pattern

The .agents/skills/ path is the interoperable standard recognized by all three agents.

Version Management

Checking for Updates

When you run nia config export --skills, Nia compares each existing skill’s frontmatter version string with the embedded version. A different string is reported as an update:

⚠ Skill updates available:
  - issue-read-github: v1.0.0 → v1.1.0
  - pr-read-github: v1.2.0 → v1.3.0

Run 'nia config export --skills --force' to update
Warning: This will overwrite existing files. Back up custom modifications first.

Updating Skills

Skills are not updated automatically to preserve your customizations. To update:

1. Back up your changes:

   cp -r .agents/skills/ .agents/skills-backup/
   

2. Re-export with force:

   nia config export --skills --force
   

3. Manually merge customizations: Review .agents/skills-backup/ and merge your changes back

Version Field

The version field in SKILL.md frontmatter should follow semantic versioning:

version: "1.2.3"

• Major (1.x.x): Breaking changes to skill structure or commands
• Minor (x.2.x): New features or commands added
• Patch (x.x.3): Bug fixes, clarifications, typo corrections

Nia currently detects only whether version strings differ; it does not determine whether the embedded version is semantically newer.

Troubleshooting

Skill Not Loading

If an agent doesn’t load your skill:

1. Check skill location: Ensure it’s in .agents/skills/<skill-name>/
2. Verify frontmatter: Ensure YAML is valid with --- delimiters
3. Check name field: Must match directory name exactly
4. Validate markdown: Ensure no syntax errors in body

Skill Update Not Detected

If nia config export --skills doesn’t detect updates:

1. Check version field: Ensure both files contain a nonempty version (for example, “1.0.0”)
2. Verify frontmatter: Version field must be in frontmatter, not body
3. Re-export with force: Use --force to overwrite and update

Custom Skill Not Used

If agent uses built-in skill instead of custom:

1. Check method: Ensure method = "skill" in toolchain.toml
2. Verify skill_name: For custom tools, set skill_name field
3. Check precedence: Project skills override user skills
4. Check the description: It must reference {{skill_name}} so the final prompt names the skill
5. Check the file: Custom skills are not exported by Nia; create .agents/skills/<skill_name>/SKILL.md

See Also

• Toolchain Configuration Guide - Configure access methods
• Utility Command Reference - Export skills command
• Agent Skills Standard - Official specification