Custom Skills

Skills are slash commands that automate complete workflows with Claude Code. When you type /implement in your terminal, Claude Code reads the instructions from the corresponding skill and executes a predefined sequence of steps: read the task, write code, run tests, and move the item to the correct column.

Almirant includes built-in skills that cover the most common workflows, but you can create your own skills to tailor them to your team's needs.

Built-in Skills

Almirant includes these skills by default:

Skill	Description
/implement	Reads the assigned work item, implements the necessary code, and moves the task to the Review column
/review-task	Reviews the current implementation by comparing it against the work item definition and its definition of done
/validate	Full validation pipeline: code review + test execution + screenshots
/test-task	Generates automated tests for the current implementation and runs them
/pr	Creates a Pull Request on GitHub from the current branch with a generated description
/ideate	Starts an interactive brainstorming session and creates work items from the ideas
/create-tasks	Creates well-structured work items with title, description, acceptance criteria, and estimation

How each skill works

/implement

1. Reads the assigned work item from Almirant via MCP
2. Analyzes the description, acceptance criteria, and definition of done
3. Explores the existing codebase to understand the context
4. Implements the necessary changes
5. Moves the work item to the Review column

/review-task

1. Retrieves the work item and its definition of done from Almirant
2. Reads the implemented code changes
3. Compares the implementation against the acceptance criteria
4. Generates a detailed report with findings and suggestions

/validate

1. Runs /review-task to review the implementation
2. Runs the project's tests
3. If there is a UI, takes screenshots for visual verification
4. Generates a consolidated report with the result of each step

/test-task

1. Reads the work item to understand what needs to be tested
2. Analyzes the current implementation
3. Generates unit and/or integration tests
4. Runs the tests and reports the results

/pr

1. Analyzes the commits and changes on the current branch
2. Generates a title and description for the Pull Request
3. Creates the PR on GitHub with the generated information

/ideate

1. Starts an interactive dialogue to explore ideas
2. Asks questions to refine the concepts
3. Converts the ideas into structured work items in Almirant

/create-tasks

1. Receives a high-level description of what is needed
2. Breaks the work down into granular tasks
3. Creates the work items in Almirant with all the necessary information

Creating custom skills

Skills are defined as Markdown files inside the .claude/skills/ directory of your project.

Location

your-project/
  .claude/
    skills/
      implement.md
      review-task.md
      my-custom-skill.md    # <-- your custom skill

Structure of a skill

Each skill file has two parts:

1. Frontmatter: metadata in YAML format (name and description)
2. Instructions: steps that Claude Code should follow, written in Markdown

---
name: my-skill
description: Brief description of what this skill does
---

## Instructions for the agent

1. Step one: detailed description
2. Step two: detailed description
3. Step three: detailed description

Example: deploy skill

---
name: deploy-staging
description: Deploys the current branch to the staging environment
---

## Instructions

1. Verify there are no uncommitted changes by running `git status`
2. Run the linter with `bun run lint` and fix any errors
3. Run the tests with `bun run test` and verify they pass
4. Push the current branch to origin
5. Deploy to staging with `bun run deploy:staging`
6. Verify the deploy was successful by checking the staging URL
7. Report the result to the user with the environment URL

Example: documentation skill

---
name: document-feature
description: Generates technical documentation for an implemented feature
---

## Instructions

1. Read the work item associated with the feature from Almirant using MCP
2. Identify the new or modified files in the implementation
3. For each new component/module:
   - Generate a JSDoc with description, parameters, and examples
   - If it is a hook, document the return values
   - If it is an endpoint, document the request/response
4. Update the domain README if it exists
5. Create a comment on the work item with a summary of the generated documentation

Example: database migration skill

---
name: db-migrate
description: Generates and applies database migrations safely
---

## Instructions

1. Read the pending changes in the schema files (`backend/packages/database/src/schema/`)
2. Generate the migration with `bun run db:generate`
3. Review the generated SQL in the migrations folder
4. If the SQL contains destructive operations (DROP, ALTER with data loss),
   warn the user and wait for confirmation before continuing
5. Apply the migration with `bun run db:migrate`
6. Verify the migration was applied successfully

Best practices

Clear and specific instructions

Write instructions that leave no room for ambiguity. Instead of "review the code", specify which files or patterns should be reviewed.

# Less effective
1. Review the code
2. Make the necessary changes

# More effective
1. Read all files in `src/domains/[feature]/` to understand the structure
2. Verify that presentational components do not contain useState or useEffect
3. If you find logic in .tsx components, extract it to a custom hook in `application/hooks/`

Use MCP tools in instructions

Reference Almirant's MCP tools so the skill interacts with your board.

1. Use the `get_work_item` tool to read the assigned task
2. Implement the changes according to the description
3. Use `update_work_item` to move the task to the "Review" column

Include conditions and validations

Define what the skill should do when something fails or when there are special conditions.

3. Run the tests with `bun run test`
   - If tests fail, analyze the errors and try to fix them
   - If you cannot fix them after 2 attempts, report the failures to the user
4. If the work item has the "needs-review" tag, do not automatically move it to Done

Keep skills focused

Each skill should do one thing well. If you need a complex workflow, split it into multiple skills and combine them manually.

Tip

Start by duplicating a built-in skill and modifying it for your use case. It is easier to adapt something existing than to create from scratch.

Important

Skills are instructions for the AI, not executable scripts. Claude Code interprets them and decides how to execute each step. Write the instructions as if for a developer reading them for the first time.

Sharing skills with your team

Since skills live in .claude/skills/, they are versioned with Git alongside the rest of the project. Any team member who clones the repository will have access to the same skills.

To maintain consistency:

1. Document each skill with a clear description in the frontmatter
2. Use consistent naming conventions (kebab-case)
3. Group related skills with prefixes: deploy-staging.md, deploy-production.md
4. Review skills in code review like any other project file