Skip to content
BoldCreate

Create and manage skills

Create and manage BoldCreate skills as files in your repository.

A repository skill is a folder in your repository that contains a SKILL.md file, and you create and manage it like any other code. Skills that come from plugins are listed on the Skills tab of the Customize page. After the folder is on the branch the agent works from, the agent can use the skill in your tasks and in the tasks of anyone who works on that repository.

Use cases

  • Turn a checklist your team repeats in every review into a skill.
  • Keep long details, such as an API style guide, in reference files the agent reads only when needed.
  • Test a skill on a branch, then merge it so the whole team gets it.
  • Update a skill when your process changes, so every new run follows the new version.

Create a skill

  1. In your repository, create a folder under a skills folder. Use .boldcreate/skills/<skill-name>/. Other supported folders are listed in Skills overview.

  2. In it, create a SKILL.md file with front matter and instructions:

    ---
name: api-conventions
description: Rules for adding or changing REST endpoints. Use when you add or change an endpoint or review API code.
---

# API conventions

## Steps

1. Read references/style-guide.md before you write any code.
2. Use plural nouns for resource paths, for example /orders/{id}.
3. Return errors in the shape shown in references/error-format.json.
4. Add a test for each new endpoint.

## Done when

- The endpoint follows the style guide.
- Tests pass.

  3. Commit the files to the branch the task starts from, and push.

Or ask the agent to create it. Start a task and say:

Create a skill called api-conventions in .boldcreate/skills that…

Review the files in the Changes tab, then create a pull request. The skill is available from the next run on a branch that contains it.

Choose a good name and description

The agent sees only the name and description of each skill until it decides a skill applies. Write them for the agent.

  • Name: lowercase letters, digits, and hyphens, such as code-review or release-notes. It must match the folder name. Keep it short.
  • Description: say what the skill does and when to use it, with the keywords people use for the task. For example: “Writes release notes from merged pull requests. Use when asked for release notes, a changelog, or a summary of changes since the last tag.” The limit is 1,024 characters.

Write the instructions

Write SKILL.md as steps the agent can follow. A good structure is:

  • When to use the skill.
  • The steps, in order.
  • A “Done when” list of checks the agent should pass before it finishes.

Add reference files

Reference files keep SKILL.md short. Put long checklists, templates, examples, and scripts next to it:

.boldcreate/skills/api-conventions/
  SKILL.md
  references/style-guide.md
  references/error-format.json
  scripts/validate.ts

In SKILL.md, tell the agent when to read each file, with a relative path. The agent reads reference files only when it needs them.

Who can use a skill

A skill follows its repository’s access. Anyone who can read the repository and starts a task on it gets its skills. To share a skill with a team, commit it to a shared repository. To keep it private while you test it, use a branch or a repository only you can access. There are no per-skill scopes.

System skills, such as live-preview-tunnel, are built in and available to everyone. You can’t edit or delete them.

Edit a skill

  1. Change the files in your repository, on a branch.
  2. Merge the change.

The change applies from the next run that starts from that branch. A run already in progress keeps the version it started with, as do follow-up messages in an existing task that has already loaded the skill. Start a new task to be sure.

Delete a skill

Delete the skill’s folder from your repository and commit the change. The agent stops using the skill from the next run on that branch. Deleting is as reversible as any commit: you can restore it from Git history.

Best practices

  • Write the description for the agent. Say what the skill does and when to use it.
  • Keep one job per skill. A code-review skill and a release-notes skill work better than one large team-process skill.
  • Keep SKILL.md short. Move long details into reference files, and say when to read each one.
  • Say when the job is done. List the checks the agent should pass.
  • Review skill changes like code. Use pull requests.
  • Never put secrets in a skill. Anyone with access to the repository can read every file in it.

Troubleshooting

  • The agent does not use a skill: check that the folder is in a supported location, contains SKILL.md, and is on the branch you started the task from. Make sure the description matches your request, or name the skill in your prompt. See Skills overview.
  • The skill is ignored: check that the name matches the folder name and the front matter is valid.
  • A teammate doesn’t get the skill: commit it to a branch they work from.
Edit on Gitea