| name | brainstorm-skills |
| description | Brainstorm useful Codex skills from real project context. Use when identifying recurring workflows, drafting dotfiles-local skills, or routing portable skills to agent-skills. |
Brainstorm Skills
Goal
Identify useful Codex skills for the current repository and turn selected ideas into high-quality SKILL.md drafts.
Success means the suggested skills solve recurring work, do not duplicate existing skills, have clear trigger descriptions, and include the right repository placement.
Stop when the user has a short ranked list of skill ideas or, if requested, validated skill files.
Workflow
- Read the nearest
AGENTS.md files for project rules, commands, and conventions.
- Scan top-level project files such as
flake.nix, package.json, Cargo.toml, pyproject.toml, Makefile, justfile, Dockerfile, and CI workflows.
- Review existing project skills in
.agents/skills/*/SKILL.md.
- For portable workflows, check the dedicated
agent-skills repository rather
than a dotfiles-managed global catalog.
- Identify recurring pain points from scripts, tests, CI, docs, and config layout.
- If the user names a focus area, prioritize that area while still checking for duplication.
Skill Ideas
For each idea, provide:
### <Skill Name> (`$skill-name`)
Type: Reference | Task | Background Knowledge
Invocation: User-only | Codex-only | Both
Why: <1-2 sentences on the recurring problem>
What it does: <brief behavior>
Trigger keywords: <phrases that should activate the skill>
Complexity: Simple | Advanced (needs scripts, templates, or references)
Scope: Dotfiles-local `.agents/skills/` | Portable `agent-skills` repository
Consider only categories that match the repository:
- Code generation and scaffolding
- Testing and verification
- Code review and project-specific quality checks
- CI, deployment, and release workflows
- Documentation workflows
- Debugging and log analysis
- Refactoring and migrations
- DevOps, infrastructure, and configuration management
- Dependency management
- Repository-specific domain workflows
Quality Filters
Suggest a skill only when it:
- Solves a real recurring need visible in the repo or named by the user.
- Benefits from Codex reading, editing, generating, or verifying across files.
- Is not already covered by existing dotfiles-local or portable skills.
- Has a specific trigger and bounded outcome.
- Can be validated with a clear command, check, or review criterion when it edits files.
Present Results
Present the top 5-8 ideas grouped by category. Include a brief rationale for the top 3 based on repo evidence, such as repeated scripts, config families, CI jobs, or existing docs.
Ask which skills the user wants to create before writing files unless the user already requested implementation.
Draft Selected Skills
For each selected skill:
- Draft the full
SKILL.md with name and description frontmatter.
- Choose dotfiles-local scope for workflows specific to this repo:
.agents/skills/<name>/.
- Route portable workflows to the authoritative
agent-skills repository.
- Add
references/, scripts/, assets/, or agents/openai.yaml only when they reduce context load or make the workflow more reliable.
- For a dotfiles-local skill, verify its frontmatter name against its directory
and run the narrowest relevant repository test. Validate portable skills in
their authoritative repository; do not add a catalog, installer, or vendor
metadata here.
Authoring Notes
- Front-load trigger keywords in
description.
- Keep
SKILL.md focused; move detailed material into references/.
- Prefer
$skill-name examples for explicit invocation.
- Name real commands the agent should run instead of relying on slash-command argument substitution.
- Use
agents/openai.yaml when a skill should require explicit invocation or expose UI metadata.
