Skip to main content
Skills are reusable instruction sets that help Codex agents perform specific tasks consistently. Symphony includes several built-in skills for common workflows like committing code, landing PRs, and interacting with Linear.

​
Skill Anatomy

A skill is a Markdown file with YAML frontmatter that defines metadata and plain Markdown content that provides instructions.

​
File Structure

---
name: skill-name
description: |
  Brief description of when to use this skill
---

# Skill Name

## Goals

- What this skill accomplishes

## Steps

1. Detailed step-by-step instructions
2. Include code examples and commands

​
Frontmatter Fields

​
name
string
required
The skill identifier, typically matches the directory name
​
description
string
required
A brief description that helps determine when to invoke this skill. Should describe the trigger conditions and primary use case.

​
Built-in Skills

Symphony includes these production skills in .codex/skills/:

​
commit

Creates well-formed git commits from session history and staged changes. 
---
name: commit
description:
  Create a well-formed git commit from current changes using session history for
  rationale and summary; use when asked to commit, prepare a commit message, or
  finalize staged work.
---

# Commit

## Steps

1. Read session history to identify scope, intent, and rationale.
2. Inspect the working tree and staged changes (`git status`, `git diff`).
3. Stage intended changes, including new files (`git add -A`).
4. Choose a conventional type and optional scope (e.g., `feat(scope): ...`).
5. Write a subject line in imperative mood, <= 72 characters.
6. Write a body that includes summary, rationale, and test status.
7. Append a `Co-authored-by` trailer for Codex.
8. Wrap body lines at 72 characters.
9. Create the commit with `git commit -F <file>`.

​
linear

Uses Symphony’s linear_graphql client tool for raw Linear GraphQL operations. 
---
name: linear
description: |
  Use Symphony's `linear_graphql` client tool for raw Linear GraphQL
  operations such as comment editing and upload flows.
---

# Linear GraphQL

## Primary tool

Use the `linear_graphql` client tool exposed by Symphony's app-server session.
It reuses Symphony's configured Linear auth for the session.

Tool input: JSON object with "query" (required) and "variables" (optional) fields.

​
land

Lands a PR by monitoring conflicts, resolving them, waiting for checks, and squash-merging when green. 
---
name: land
description:
  Land a PR by monitoring conflicts, resolving them, waiting for checks, and
  squash-merging when green; use when asked to land, merge, or shepherd a PR to
  completion.
---

# Land

## Goals

- Ensure the PR is conflict-free with main.
- Keep CI green and fix failures when they occur.
- Squash-merge the PR once checks pass.
- Do not yield to the user until the PR is merged.

## Steps

1. Locate the PR for the current branch.
2. Confirm the full gauntlet is green locally before any push.
3. Check mergeability and conflicts against main.
4. If conflicts exist, use the `pull` skill to fetch/merge `origin/main`.
5. Watch checks until complete.
6. If checks fail, pull logs, fix the issue, commit, push, and re-run.
7. When all checks are green, squash-merge using PR title/body.

​
pull

Pulls latest origin/main into the current branch and resolves merge conflicts.

​
push

Pushes current branch changes to origin and creates or updates the corresponding PR.

​
Creating Custom Skills

1

Create the skill directory

Add a new directory under .codex/skills/ with your skill name:
mkdir -p .codex/skills/my-skill
2

Write SKILL.md

Create the skill file with frontmatter and instructions:
.codex/skills/my-skill/SKILL.md
---
name: my-skill
description: Brief description of when to use this skill
---

# My Skill

## Goals

- Clear objective statements

## Prerequisites

- Required tools or environment setup

## Steps

1. Detailed instructions
2. Include command examples
3. Handle error cases

## Example

```bash
# Example command usage
example-command --flag value

</Step>

<Step title="Reference the skill">
Reference your skill in WORKFLOW.md or other skills:

```markdown
## Related skills

- `my-skill`: use when you need to perform X.
3

Test the skill

Test by creating a workflow that references the skill and verifying Codex follows the instructions correctly.

​
Skill Best Practices

Be specific in descriptions: The description field helps Codex decide when to invoke a skill. Use clear trigger conditions like “use when asked to…”, “use when you need to…”

​
Structure Guidelines

  • Goals section: Start with 2-5 clear objective statements
  • Prerequisites section: List required tools, auth, or environment setup
  • Steps section: Provide numbered, actionable instructions
  • Commands section: Include copy-paste ready commands with comments
  • Error handling: Document common failure modes and remediation

​
Writing Effective Instructions

  1. Use imperative mood: “Run the command”, not “You should run the command”
  2. Include context: Explain why a step matters when it’s not obvious
  3. Provide examples: Show actual command output where helpful
  4. Handle edge cases: Document what to do when things go wrong
  5. Keep it focused: One skill should do one thing well

​
Code Examples

Include working code snippets that Codex can execute directly: 
## Commands

```bash
# Check current status
branch=$(git branch --show-current)
echo "Current branch: $branch"

# Run validation
make test


## Skill Composition

Skills can reference other skills to build complex workflows:

```markdown
## Related skills

- `commit`: produce clean commits during implementation
- `push`: keep remote branch current and publish updates
- `pull`: keep branch updated with latest `origin/main`
When one skill references another, Codex will load and follow both skill instruction sets. Use this to decompose complex workflows into reusable components.

​
Advanced Patterns

​
Conditional Logic

Use shell conditionals in command sections: 
if [ "$pr_state" = "MERGED" ]; then
  echo "Branch is tied to a merged PR; create a new branch" >&2
  exit 1
fi

​
Helper Scripts

Include helper scripts alongside SKILL.md: 
.codex/skills/land/
├── SKILL.md
└── land_watch.py
Reference them in the skill: 
## Async Watch Helper

Preferred: use the asyncio watcher to monitor review comments:

```bash
python3 .codex/skills/land/land_watch.py


### State Management

Capture and use state across skill steps:

```bash
# Capture PR number for later steps
pr_number=$(gh pr view --json number -q .number)

# Use in subsequent commands
gh api repos/{owner}/{repo}/pulls/$pr_number/comments

​
Examples from Production

​
File Upload Workflow (from linear skill)

### Upload a video to a comment

Do this in three steps:

1. Call `linear_graphql` with `fileUpload` to get `uploadUrl`, `assetUrl`, and
   any required upload headers.
2. Upload the local file bytes to `uploadUrl` with `curl -X PUT` and the exact
   headers returned by `fileUpload`.
3. Call `linear_graphql` again with `commentCreate` and include the resulting
   `assetUrl` in the comment body.

​
Loop-Based Workflow (from land skill)

# Watch checks
if ! gh pr checks --watch; then
  gh pr checks
  # Identify failing run and inspect logs
  # gh run list --branch "$branch"
  # gh run view <run-id> --log
  exit 1
fi

​
Troubleshooting

  • Check that the description field clearly describes when to use the skill
  • Ensure the skill is referenced in WORKFLOW.md or another loaded skill
  • Verify the skill file is named SKILL.md (case-sensitive)
  • Verify prerequisites are documented and met
  • Check for environment-specific assumptions (paths, tools)
  • Add error handling and fallback strategies
  • Add concrete command examples
  • Include expected output samples
  • Document decision points explicitly

Build docs developers (and LLMs) love

Get started for freeTalk to us