16 Jan 2026 4 min read opencode

opencode tweaking: mastering SKILL.md vs AGENTS.md

As OpenCode continues to revolutionize how developers interact with AI coding agents, understanding the proper organization of project configuration files becomes crucial for maximizing productivity. In this guide, we'll explore the practical differences between SKILL.md and AGENTS.md files, and how to structure them effectively across global and project-specific contexts.

Understanding the Core Concepts

What is SKILL.md?

SKILL.md files define reusable behaviors and specialized instructions that can be loaded on-demand by OpenCode agents. Think of them as specialized toolkits that agents can access when needed for specific tasks.

Key Characteristics:

Contains YAML frontmatter with metadata
Defines specific capabilities and workflows
Loaded dynamically via the skill tool
Can be permission-controlled per agent

What is AGENTS.md?

AGENTS.md serves as a comprehensive knowledge base for your project, providing all agents with essential context about codebase structure, coding conventions, and development workflows.

Key Characteristics:

Project-specific documentation
Shared across all agents
Contains development guidelines
Helps agents understand project context

Practical Organization Structure

Global Skills: Your Reusable Toolkit

Global skills should live in ~/.config/opencode/skill/ and contain workflows you use across multiple projects:

~/.config/opencode/skill/
├── git-release/SKILL.md          # Release management workflows
├── npm-publish/SKILL.md           # Package publishing patterns
├── docker-build/SKILL.md          # Docker containerization
├── security-audit/SKILL.md         # Security review processes
└── testing/SKILL.md               # Testing best practices

Example: git-release/SKILL.md

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do
- Draft release notes from merged PRs
- Propose semantic version bumps
- Generate copy-pasteable `gh release create` commands

## When to use me
Use this when preparing tagged releases. Ask clarifying questions if the target versioning scheme is unclear.

Project Skills: Domain-Specific Expertise

Project-specific skills belong in .opencode/skill/ and contain workflows unique to your project:

my-project/.opencode/skill/
├── api-endpoint/SKILL.md          # Project API patterns
├── database-migration/SKILL.md    # Database schema changes
├── component-style/SKILL.md        # UI component conventions
└── deployment/SKILL.md             # Project deployment workflows

Global Agents: Cross-Project Specialists

Global agents in ~/.config/opencode/agent/ provide specialized expertise across all projects:

~/.config/opencode/agent/
├── security-reviewer.md           # Security analysis expert
├── performance-analyzer.md        # Performance optimization
├── documentation-writer.md        # Technical documentation
└── code-reviewer.md               # Code review patterns

Example: security-reviewer.md

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are a security expert. Focus on identifying potential security issues:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

Provide constructive feedback without making direct changes.

Project Agents: Domain-Specific Assistants

Project agents in .opencode/agent/ understand your specific project architecture and conventions:

my-project/.opencode/agent/
├── api-designer.md                # API design patterns
├── frontend-architect.md          # Frontend conventions
├── backend-specialist.md          # Backend patterns
└── test-automation.md            # Testing strategies

AGENTS.md: Project Context Hub

The AGENTS.md file in your project root serves as the central knowledge base:

# Development Guide

## Architecture
- Microservices architecture with Node.js/TypeScript
- PostgreSQL for primary data storage
- Redis for caching and session management
- Docker containerization for deployment

## Coding Conventions
- ESLint + Prettier for code formatting
- TypeScript strict mode enabled
- Jest for unit and integration testing
- Git flow branching strategy

## Development Commands
- `npm run dev` - Start development server
- `npm test` - Run test suite
- `npm run build` - Production build
- `npm run lint` - Code quality checks

## API Patterns
- RESTful endpoints with OpenAPI documentation
- Consistent error response format
- Request validation middleware
- Rate limiting on all endpoints

## Database Guidelines
- All migrations must be reversible
- Use foreign key constraints
- Index frequently queried columns
- Connection pooling configured

Priority and Override Rules

Understanding how OpenCode resolves conflicts between different configurations is essential:

Project overrides Global: Local definitions always take precedence
Specific overrides Generic: Specialized skills/agents override general ones
Context matters: Use project-specific for domain knowledge, global for reusable patterns

Permission Management

OpenCode provides granular control over which agents can access specific skills:

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

Permission Levels:

allow: Skill loads immediately
deny: Skill hidden from agent
ask: User prompted for approval

Best Practices

1. Start Small, Grow Organically

Begin with essential skills and agents, then expand based on your team's needs.

2. Keep Skills Focused

Each SKILL.md should solve a specific problem or workflow. Avoid creating monolithic skills.

3. Document Everything

Maintain clear descriptions in frontmatter to help agents choose the right skill for the task.

4. Version Control Your Configuration

Commit AGENTS.md and project-specific skills/agents to your repository for team consistency.

5. Regular Review and Cleanup

Periodically review and remove unused skills or agents to maintain clarity.

Common Use Cases

When to Use Global Skills

Git workflows (release, branching, tagging)
Package management (npm, pip, cargo)
Container operations (Docker, Kubernetes)
Testing frameworks (Jest, pytest, JUnit)

When to Use Project Skills

API endpoint patterns
Database schema migrations
Component styling conventions
Deployment procedures

When to Use Global Agents

Security auditing across projects
Performance analysis
Documentation standards
Code review processes

When to Use Project Agents

Project architecture guidance
Domain-specific business logic
Team-specific coding standards
Technology stack expertise

Advanced Configuration

Custom Agent Creation

Use the interactive command to create new agents:

opencode agent create

This will guide you through:

Choosing global or project-specific location
Defining agent purpose and description
Selecting appropriate tools and permissions
Generating the agent configuration

Skill Discovery

OpenCode automatically discovers skills from multiple locations:

Project config: .opencode/skill/<name>/SKILL.md
Global config: ~/.config/opencode/skill/<name>/SKILL.md
Claude-compatible: .claude/skills/<name>/SKILL.md

Troubleshooting

If skills aren't appearing:

Verify SKILL.md is spelled in all caps
Check frontmatter includes required name and description
Ensure skill names are unique across locations
Verify permissions aren't set to deny

Conclusion

Proper organization of SKILL.md and AGENTS.md files is fundamental to maximizing OpenCode's effectiveness. By following these guidelines, you'll create a robust configuration that:

Enhances agent capabilities with specialized skills
Provides consistent project context across all agents
Maintains clear separation between global and project-specific concerns
Enables granular permission control for security and governance

Start implementing these patterns today, and watch your OpenCode productivity soar as your agents become more capable, context-aware, and aligned with your development workflows.

This guide reflects OpenCode best practices as of January 2026. For the latest updates, refer to the official OpenCode documentation at opencode.ai/docs.