Skip to main content
Skills are defined as SKILL.md files inside a named directory. This page covers everything you need to know to write effective skills.

​
File Structure

Place skills in the appropriate directory depending on scope: 
# Project-specific (committed to git)
.cognition/skills/
└── my-skill/
    └── SKILL.md

# Global — available in all projects (not committed)
~/.config/cognition/skills/
└── my-skill/
    └── SKILL.md
The directory name is the skill’s identifier (used for /my-skill invocation). The SKILL.md file contains optional YAML frontmatter and the skill’s prompt content.

​
Frontmatter Reference

---
name: my-skill
description: What this skill does (shown in completions)
argument-hint: "[file] [options]"
model: sonnet
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Read(src/**)
  deny:
    - exec
  ask:
    - Write(**)
triggers:
  - user
  - model
---

Your prompt content goes here...

​
All Frontmatter Fields

FieldTypeDefaultDescription
namestringdirectory nameDisplay name of the skill
descriptionstringnoneShown in slash command completions
argument-hintstringnoneHint shown after the command name (e.g., [filename])
modelstringcurrent modelOverride the model for this skill
allowed-toolslistall toolsRestrict which tools the skill can use
permissionsobjectinheritPermission overrides for this skill
triggerslist[user, model]How the skill can be invoked

​
Prompt Content

The body of the SKILL.md file (after the frontmatter) is the prompt that gets injected when the skill is invoked.

​
Dynamic Content

Skills support three types of dynamic content in the prompt body:
Interpolate user-provided arguments:
---
name: explain
argument-hint: "[file]"
---

Please explain the code in $1 in detail.
All arguments: $ARGUMENTS
  • $1, $2, etc. — Individual positional arguments
  • $ARGUMENTS — All arguments as a single string

​
Permissions

Skills can define their own permission scope using the same syntax as the main permissions config: 
permissions:
  allow:
    - Read(src/**)
    - Exec(npm run test)
  deny:
    - Write(/etc/**)
    - exec
  ask:
    - Write(src/**)
How skill permissions work:
  • allow — These scopes are auto-approved during skill execution
  • deny — These scopes are blocked during skill execution
  • ask — These scopes always prompt the user
Skill permissions are additive to (not replacing) the session’s base permissions. A skill cannot grant permissions that are denied at a higher level (project or organization config).

​
Allowed Tools

Restrict which tools the skill can use: 
allowed-tools:
  - read
  - grep
  - glob
Available tool names: read, edit, grep, glob, exec You can also allow MCP tools: 
allowed-tools:
  - read
  - mcp__github__list_issues
  - mcp__github__create_issue
If allowed-tools is not specified, the skill has access to all tools. For safety-critical skills, always restrict to the minimum needed.

​
Examples

​
Code Review Skill

---
name: review
description: Review staged changes for issues
allowed-tools:
  - read
  - grep
  - glob
  - exec
permissions:
  allow:
    - Exec(git diff)
    - Exec(git log)
---

Review the current changes for quality issues:

!`git diff --staged`

Evaluate:
1. **Correctness** — Any logic errors or edge cases?
2. **Security** — Any vulnerabilities introduced?
3. **Performance** — Any obvious inefficiencies?
4. **Style** — Consistent with the codebase?

Provide a summary with specific line references.

​
Component Generator

---
name: component
description: Generate a React component from a description
argument-hint: "<ComponentName>"
allowed-tools:
  - read
  - edit
  - grep
  - glob
model: sonnet
permissions:
  allow:
    - Write(src/components/**)
---

Create a new React component named `$1`:

1. Check existing components in src/components/ for style conventions
2. Create the component file at src/components/$1/$1.tsx
3. Create a barrel export at src/components/$1/index.ts
4. Add basic tests at src/components/$1/$1.test.tsx
5. Follow the patterns you find in existing components

​
Deployment Checklist

---
name: deploy
description: Run through the deployment checklist
triggers:
  - user
allowed-tools:
  - read
  - exec
  - grep
permissions:
  allow:
    - Exec(npm run)
    - Exec(git)
---

Run through the deployment checklist:

1. Run the test suite: `npm run test`
2. Run the linter: `npm run lint`
3. Check for uncommitted changes: `git status`
4. Verify the build: `npm run build`
5. Show the current branch and last commit

Report the status of each step. If anything fails, stop and explain the issue.

​
Search Expert

---
name: find
description: Find relevant code across the project
argument-hint: "<what to find>"
allowed-tools:
  - read
  - grep
  - glob
triggers:
  - user
  - model
---

Search the codebase thoroughly for: $ARGUMENTS

Use grep for content search and glob for file discovery.
Provide relevant file paths and code snippets.
Explain how the pieces connect.

​
Tips

Keep prompts focused

A skill should do one thing well. Create multiple skills rather than one mega-skill.

Include examples

Show the agent what good output looks like in your prompt.

Use allowed-tools

Restricting tools makes skills safer and more predictable.

Test with /skill-name

Invoke your skill and iterate on the prompt until the output is what you want.