setup
Use when initializing Beat or updating its config — not for editing config.yaml directly or non-Beat tools
How do I install this agent skill?
npx skills add https://github.com/kirkchen/beat --skill setupIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill initializes a configuration for the Beat tool. It scans local project documentation and manifest files to automatically generate coding standards and detect the technology stack. This processing of untrusted project data presents a minor risk of indirect prompt injection.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Initialize Beat configuration in the current project.
<decision_boundary>
Use for:
- Setting up Beat for the first time in a project
- Updating existing Beat configuration (language, testing frameworks, rules)
- Detecting project tech stack and recommending test frameworks
- Setting up or completing
docs/agents/issue-tracker.md,CODING_STANDARDS.mdor the Agent docs block
NOT for:
- Editing
beat/config.yamldirectly (just edit the file) - Configuring non-Beat tools or project settings
- Creating changes or writing feature files (use
/beat:design)
</decision_boundary>
Input: None required. The skill gathers information interactively.
Steps
-
Check if config already exists
Check if
beat/config.yamlexists.- If yes: read it, show current config, ask if user wants to update or keep it
- If no: proceed to creation
Keeping the config skips steps 3–7 only; steps 8–11 still run, so a project set up before the layout files existed gets them now.
Also check for
beat/CONTEXT.md(the glossary path before 0.6). If it exists, print exactly this one line and continue with setup:This project still has beat/CONTEXT.md. Run the migration: https://github.com/kirkchen/beat/blob/main/docs/migrations/0.6-project-layout.mdDo not migrate it, move it, or create
GLOSSARY.mdin its place. The migration is the user's step. -
Check superpowers dependency
Check if the superpowers plugin is available by looking for any
superpowers:*skill in the skill list.If not available:
"Beat works standalone, but is better with superpowers — it provides structured brainstorming, TDD discipline, task decomposition, and git worktree isolation.
Install it yourself (an agent cannot run plugin commands):
- Claude Code:
/plugin install superpowers@claude-plugins-official - Codex: open
/plugins, search forsuperpowers, choose Install
Without it, Beat falls back to simpler built-in flows."
Use AskUserQuestion tool:
- "I installed it" -- check the skill list again; if
superpowers:*is still missing, say a restart may be needed and continue - "Continue without it"
If available: proceed silently.
- Claude Code:
-
Ask artifact language
Use AskUserQuestion tool:
"What language should Beat use for artifacts (proposals, features, designs, tasks)?"
Provide options:
- "English (en)" -- default
- "繁體中文 (zh-TW)"
- "简体中文 (zh-CN)"
- Other -- let user specify a BCP 47 tag
This sets the
languagefield in config. -
Gather project context and detect tech stack
Use AskUserQuestion tool to ask:
"Describe your project so Beat can tailor its artifacts. Include: tech stack, test framework, and any key conventions."
Provide example options:
- "Let me describe it" -- open-ended input
- "Detect from codebase" -- agent scans package.json, Cargo.toml, go.mod, etc.
If user chooses detection:
- Scan common manifest files for tech stack and primary language
- Look for test configuration (vitest.config, jest.config, pytest.ini, etc.)
- Look for BDD runner configuration (cucumber.js, behave.ini, etc.)
- Look for e2e configuration (playwright.config, cypress.config, etc.)
- Check for linter/formatter configs
- Summarize findings and confirm with user
Record the detected/described tech stack — this informs Step 5 framework recommendations.
-
Configure test frameworks
Based on the tech stack from Step 4, recommend appropriate frameworks.
Step 5a: Ask project type
Use AskUserQuestion tool:
"What type of project is this?"
- "Web app (has UI)" -- needs browser automation for e2e
- "API server" -- needs HTTP client for e2e
- "CLI tool" -- needs process execution for e2e
- "Library / SDK" -- e2e usually not needed, behavior tests suffice
Step 5b: Recommend frameworks using the table below
Cross-reference (language × project type) to recommend a framework pair. Present as defaults the user can accept or customize:
"Based on your stack ({language} + {project type}), recommended test frameworks:
- Behavior tests: {recommendation}
- E2E tests: {recommendation}
Accept defaults or customize?"
Framework recommendation table:
Behavior test frameworks (UT / integration):
Language Primary Alternative TypeScript / JavaScript vitest jest Python pytest pytest-bdd Go go test — Java JUnit TestNG C# xUnit NUnit Ruby RSpec — Rust cargo test — E2E frameworks (BDD runner + driver, by project type):
Language Web app (UI) API server CLI tool TS / JS cucumber-js + playwright cucumber-js + supertest cucumber-js + execa Python behave + playwright behave + requests behave + subprocess Go godog + playwright godog + net/http godog + os/exec Java Cucumber-JVM + Selenium Cucumber-JVM + RestAssured Cucumber-JVM + ProcessBuilder C# Reqnroll + Playwright Reqnroll + HttpClient Reqnroll + Process Ruby Cucumber + Capybara Cucumber + Faraday Cucumber + Open3 For Library projects: omit
testing.e2e— behavior tests are sufficient. Note this in the summary.Step 5c: Escape hatch
If the user explicitly says tests are not needed (e.g., pure docs, config-only, infra project):
- Set
testing.required: false - Do NOT push back — respect the user's judgment
This sets the
testingfield in config:testing: behavior: <selected framework> # always set (unless testing.required: false) e2e: <selected BDD runner + driver> # set unless Library type or testing.required: false -
Ask about artifact rules (optional)
Use AskUserQuestion tool:
"Want to set rules for how artifacts are generated?"
- "Yes, let me specify" -- ask per-artifact rules (
proposal,gherkin,design,tasks, andadrfor ADRs written at any trigger point) - "Skip for now" -- create config with context only
If
docs/adr/TEMPLATE.mdalready exists, mention that skills will use it as the ADR skeleton automatically —rules.adris for constraints beyond the template (e.g. an index to update). - "Yes, let me specify" -- ask per-artifact rules (
6b. Prototype surface (only when detectable)
If the project has a Storybook (.storybook/ directory or a storybook script in package.json) or another obvious prototype surface, set prototype.surface and prototype.command in the config without asking — /beat:explore uses them when exploration ends in a prototype node. Otherwise leave the field out; it can be added later.
-
Write config
Create
beat/config.yamlfollowing the schema inreferences/config-schema.md.mkdir -p beatWrite the file with the gathered context and rules.
-
Create directory structure (if not exists)
mkdir -p beat/changes mkdir -p beat/featuresDo not create the three living-doc surfaces here. They are
GLOSSARY.md,docs/adr/andbeat/ARCHITECTURE.md(plus module READMEs), all lazy: each appears the first time a Beat skill needs it, and a small project may never need any of them. Their paths are mapped inreferences/project-layout.md. Mention this in the summary so the user knows what to expect.
Steps 9–11 write the project-layout files from references/project-layout.md. Each is idempotent: an existing file is completed (missing sections or placeholders filled) or kept as is, never overwritten, and the user's edits are kept. Re-running setup changes nothing that is already filled in.
-
Issue tracker (
docs/agents/issue-tracker.md)Detect the tracker from
git remote -v:- a
github.comremote → templatereferences/issue-tracker-github.md - a
gitlabhost (gitlab.com or a self-hostedgitlab.*) → templatereferences/issue-tracker-gitlab.md - any other host, or no remote → template
references/issue-tracker-other.md
Ask with AskUserQuestion tool only when detection is ambiguous (remotes on more than one host, or a host that may be a self-hosted GitHub / GitLab). Put the detected answer first as the recommended option.
Fill these setup placeholders, everywhere they appear in the template:
<owner>/<repo>(GitHub) or<group>/<project>(GitLab): from the remote URL. Forissue-tracker-other.md, ask for<tracker name>and<tracker location>instead (e.g. "Jira", "project ABC").<assignee>: ask "Which account does the orchestrator run as? (the GitHub / GitLab login that will own the PRs)".<dispatch-label>: ask "Which label hands an issue to your orchestrator? (answer none if the project does not dispatch issues)". Beat has no default: the label belongs to whatever picks the issues up. Fill innonewhen there is none.
Every other
<...>in the template (<number>,<file>,<parent>,<n>, ...) is a command argument the skills fill at run time: leave it as written.For
issue-tracker-other.md, ask the user for the one-paragraph Conventions description; if they have none yet, leave its placeholder text in place.Copy the Vocabulary section as is, apart from the
<assignee>and<dispatch-label>edits above: the fivestatus/*labels and their meanings are fixed, not per project.Write
docs/agents/issue-tracker.md(mkdir -p docs/agents). If the file exists, fill only the setup placeholders still in it and add any template section it lacks; keep everything else. - a
-
Coding standards (
CODING_STANDARDS.md)If
CODING_STANDARDS.mdalready exists at the project root, keep it as is. If it is absent, write it fromreferences/coding-standards-template.mdand fill## Sourcesby scanning:CONTRIBUTING.mdREADME.mdfiles at the root and one level undersrc/,packages/,apps/: headings containing convention, invariant, testing or styledocs/**files whose name contains convention, standard, style or guideline
One line per hit:
path — the heading or first sentence. If nothing is found, leave the Sources placeholder. Leave## Judgement ruleswith its placeholder;/retroand reviewers fill it later. -
Agent docs block (
CLAUDE.mdorAGENTS.md)Pick the file: when both
CLAUDE.mdandAGENTS.mdexist, write the block into both (Claude Code reads one, Codex the other), once if one is a symlink to the other. Otherwise use whichever exists, or ask with AskUserQuestion tool which one to create (CLAUDE.mdfor Claude Code,AGENTS.mdfor Codex and other agents).Insert the
## Agent docsblock fromreferences/project-layout.md(the heading plus its three pointer lines). If the file already has a## Agent docsheading, replace Beat's three pointer lines in that section in place; keep any other lines the user added. Never add a second block.The block points at
GLOSSARY.mdeven when the glossary does not exist yet: the pointer tells agents where it goes. Do not createGLOSSARY.mdto satisfy it. -
Show summary
## Beat Initialized **Config:** beat/config.yaml **Directories:** beat/changes/, beat/features/ **Superpowers:** installed / not installed (fallback mode) **Testing:** {behavior framework} + {e2e framework} (or "not required") **Issue tracker:** docs/agents/issue-tracker.md ({GitHub | GitLab | other}) — written / completed / kept **Coding standards:** CODING_STANDARDS.md — written ({n} sources) / kept **Agent docs:** {CLAUDE.md | AGENTS.md | both} — block added / updated / kept Your config will be used when creating artifacts. Edit beat/config.yaml anytime to update preferences. Beat will also lazy-create three living-doc surfaces when first needed: - GLOSSARY.md — domain glossary (see references/context-format.md) - docs/adr/ — ADRs, three-condition gate (see references/adr-format.md) - beat/ARCHITECTURE.md + module READMEs (see references/architecture-format.md) Small projects may never need any of these. Ready to start? Run `/beat:design` or `/beat:explore`Then end with the handoff block from
references/handoff-report.md(next: /beat:explore).
Guardrails
- Never overwrite existing config without asking
- Config is always optional -- if user wants minimal setup, just create directories
- Validate config against
references/config-schema.mdbefore writing - Context should be concise -- warn if it exceeds 2KB (soft limit, 50KB hard limit)
- Framework recommendations are suggestions -- always let the user override
- Do not insist on e2e for Library projects
- Never overwrite
docs/agents/issue-tracker.md,CODING_STANDARDS.md, or the rest ofCLAUDE.md/AGENTS.md: complete them, do not replace them - Never create
GLOSSARY.mdordocs/adr/; never migratebeat/CONTEXT.md(print the one-line pointer instead) - Do not skip
docs/agents/issue-tracker.mdbecause the project has no orchestrator yet:/beat:to-issuerefuses without it; write it now, it is one file
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/kirkchen/beat/setup">View setup on skillZs</a>