repos-add
Use to add a code repository to this workspace's manifest, table and your clones, through a merge request.
- License 许可
- MIT
- 最近更新
- 2026-10-30
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- repos-add
- description
- Use to add a code repository to this workspace's manifest, table and your clones, through a merge request.
03 SKILL.md 正文
Add a repository
Steps
-
Go to the workspace root: the nearest directory, walking up from where you are, where
test -f .agents/kit.jsonsucceeds. Run every command below from there. -
Collect inputs from the person:
remote(required): the clone URL or path.name: default is the last path segment of the remote without.git(forgit@gitlab.example.com:team/payments-worker.gitit ispayments-worker).roles: ask for one or more names; the allowed names are the file names without.mdprinted byls .agents/roles/.summary: ask for one line.kit(optional): only when the person names a repository kit kind. The allowed kinds are the folder names printed byls .agents/repo-kits/. When that folder is missing or empty, tell the person that this workspace has no repository kits, and the entry gets nokit. When the person names a kind that is not in the list, tell them the allowed kinds and ask again. With a kind, collect its parameters:- Read
.agents/repo-kits/<kind>/kit.json. Itsparamsobject lists every parameter, each withdescriptionandpattern. - For every parameter, in the order of
params, show the person its name,descriptionandpattern, and ask for the value. - The whole value must match
pattern, not only a part of it:opsmatches[a-z]+,ops-1does not. Whencommand -v python3succeeds, check withPATTERN='<pattern>' VALUE='<value>' python3 -c 'import os, re, sys; sys.exit(0 if re.fullmatch(os.environ["PATTERN"], os.environ["VALUE"]) else 1)'; exit code 0 means it matches. The pattern and value travel in environment variables so the Python code never contains them. Inside the single-quoted shell values write each'as'\''; for example the valueit'sbecomesVALUE='it'\''s'. On a value that does not match, tell the person the pattern and ask for that parameter again. - Do not install the kit into the clone in this skill. Installation is the
repo-kit-installskill, run after this merge request is merged.
- Read
- Never invent roles, summary, a kit kind or kit parameter values. If the person gives no roles or no summary, ask again. The kit kind is optional: when the person names none, the entry gets no
kitand you do not ask for one again.
-
Set
forge. Use the value the person gave. Otherwise find the remote host:git@host:path(for examplegit@gitlab.example.com:team/app.git): the host is the text between@and the first:, heregitlab.example.com;ssh://git@host/pathorssh://host/path: removessh://, then the text before the first/, without anyuser@before it and any:portafter it;https://host/pathorhttp://host/path: remove the scheme, then the text before the first/, without anyuser@before it and any:portafter it.
Then choose
forgeby the host:- host contains
gitlab→gitlab; - host is
github.com→github; - a local path or a
file://remote →git; - any other host → ask the person to choose
gitlab,githuborgit.
-
Read
repos.json. If any entry has the samenameor the sameremote, stop, tell the person which entry matches, and change nothing. -
Run
git ls-remote --symref <remote> HEAD. The output lineref: refs/heads/<branch> HEADgivesdefault_branch=<branch>.- When the command succeeds but prints no line starting with
ref:(the remote is an empty repository), ask the person fordefault_branch. - When the command fails, stop and ask the person whether to add the entry without cloning. With no answer, stop and change nothing.
- When the person says no, stop and change nothing.
- When the person says yes, ask the person for
default_branchand skip step 9.
- When the command succeeds but prints no line starting with
-
Find the workspace default branch: run
git symbolic-ref --short refs/remotes/origin/HEADand remove theorigin/prefix; when the command fails, usemain. Call it<default>. Then run, one by one:git switch <default>git pull --ff-onlygit switch -c repos-add-<name>
-
Edit
repos.json: append the entry as the last element ofrepositories. Keys go in the ordername,remote,forge,default_branch,roles,summary, andkitlast when the person named a kit.kitis an object with the keyskindandparams, in this order;paramsholds every parameter collected in step 2 in the order of the kit'sparams. Use two-space indentation and put each list item and each object key on its own line, exactly as in the example below. When the list already has entries, add a comma after the closing}of the previous last entry. Inside every JSON string value write"as\"and\as\\; for example the summaryReads "raw" C:\databecomes"summary": "Reads \"raw\" C:\\data". -
If
command -v python3succeeds, runpython3 tools/generate.py. Otherwise apply## Recipe: repository table. -
Unless the person chose to add without cloning, run
git clone <remote> repos/<name>. Do not add or change any file in the clone, including.agents/. -
Run the check. First run
command -v python3.- When it succeeds (Python is present): run
python3 tools/check.py. Fix findings only inrepos.jsonandREPOSITORIES.md, the files this skill changed, and run it again. Stop running it when no finding names either file. If findings in other files remain, do not fix them; list them in the report. - When it fails (Python is missing): do not run the check. Remember the line
check not run: python3 missingfor the report.
- When it succeeds (Python is present): run
-
Commit: run
git add repos.json REPOSITORIES.md, thengit commit -m "chore(repos): add <name>". -
Run
git pull --rebase origin <default>. On conflicts follow## Conflicts. After the conflicts are resolved and the rebase has finished, go back to step 10 and run it again before step 13. -
Push and open the merge request by
.agents/rules/merge-requests.md, with titleAdd repository <name>and branchrepos-add-<name>. Choose how to open it byparams.forgein.agents/kit.json, the forge of this workspace. Do not use theforgeyou set in step 3; that one belongs to the new repository. -
Report to the person:
- the branch
repos-add-<name>; - the merge request link, or the instruction to open it;
- the clone result (
repos/<name>cloned, or skipped without cloning); - when the entry has
kit: the kit kind is recorded but not installed; after the merge request is merged, install it with therepo-kit-installskill; - as the last line, the check result, or
check not run: python3 missing.
- the branch
Recipe: repository table
In REPOSITORIES.md, between <!-- repos:begin --> and <!-- repos:end -->, add one line directly above <!-- repos:end -->:
| <name> | <forge> | <default_branch> | <roles joined with ", "> | <kit.kind> | <summary> |
When the entry has no kit, the <kit.kind> cell is empty: write the two spaces around it, | backend, qa | | Consumes. Only kit.kind goes into the table; never write kit parameters there.
Change nothing else in the file.
Example. The person adds two repositories, one after the other:
payments-workerwith remotegit@gitlab.example.com:team/payments-worker.git, forgegitlab, default branchmain, rolesbackendandqa, summaryConsumes payment events and writes postings, no kit;abs-operationswith remotegit@gitlab.example.com:team/abs-operations.git, forgegitlab, default branchmaster, rolefrontend, summaryOperations micro frontend, kitmfe. Themfekit declaresMFE,BFFandPREFIXin this order; the person givesabs-operations,abs-operations-bffandops.
repos.json after adding both:
{
"repositories": [
{
"name": "payments-worker",
"remote": "git@gitlab.example.com:team/payments-worker.git",
"forge": "gitlab",
"default_branch": "main",
"roles": [
"backend",
"qa"
],
"summary": "Consumes payment events and writes postings"
},
{
"name": "abs-operations",
"remote": "git@gitlab.example.com:team/abs-operations.git",
"forge": "gitlab",
"default_branch": "master",
"roles": [
"frontend"
],
"summary": "Operations micro frontend",
"kit": {
"kind": "mfe",
"params": {
"MFE": "abs-operations",
"BFF": "abs-operations-bff",
"PREFIX": "ops"
}
}
}
]
}
Table block in REPOSITORIES.md before:
<!-- repos:begin -->
| Name | Forge | Default branch | Roles | Kit | Summary |
|---|---|---|---|---|---|
<!-- repos:end -->
Table block in REPOSITORIES.md after:
<!-- repos:begin -->
| Name | Forge | Default branch | Roles | Kit | Summary |
|---|---|---|---|---|---|
| payments-worker | gitlab | main | backend, qa | | Consumes payment events and writes postings |
| abs-operations | gitlab | master | frontend | mfe | Operations micro frontend |
<!-- repos:end -->
Conflicts
- List conflicted files:
git diff --name-only --diff-filter=U. - First check the list for any file other than
REPOSITORIES.md, includingrepos.json. If there is one:- Run
git rebase --abort. - For each such file, show the person both versions:
git diff <default>...repos-add-<name> -- <file>andgit show origin/<default>:<file>. - Stop and wait for the person. Do not touch
REPOSITORIES.md.
- Run
- Only when
REPOSITORIES.mdis the sole conflicted file:- Run
git checkout --ours -- REPOSITORIES.md. During a rebase--oursis the default branch version. - Regenerate the table: if
command -v python3succeeds, runpython3 tools/generate.py; otherwise rebuild the table by hand as below. - Without Python, replace the two header lines below
<!-- repos:begin -->with| Name | Forge | Default branch | Roles | Kit | Summary |and|---|---|---|---|---|---|, and delete every row between that separator and<!-- repos:end -->. Then, for each entry ofrepositoriesinrepos.json, from first to last, add its row directly above<!-- repos:end -->by## Recipe: repository table, with theKitcell from the entry'skit.kindor empty. Keep the two marker lines. The table then has one row per entry inrepos.jsonorder. - Run
git add REPOSITORIES.md. - Run
GIT_EDITOR=true git rebase --continue.
- Run
Without Python
- In step 8, apply
## Recipe: repository tableinstead ofpython3 tools/generate.py. - In step 2, check each kit parameter value against its
patternwithprintf '%s\n' '<value>' | grep -Ex -e '<pattern>'; exit code 0 means the whole value matches. Write each'inside the quotes as'\''. When a pattern uses syntaxgrep -Edoes not support, such as\d,\w,\s,(?or a lazy*?, compare by reading instead. A value with a line break never matches. - Skip
python3 tools/generate.pyandpython3 tools/check.pyeverywhere, including## Conflicts. - End the report with the line:
check not run: python3 missing
04 同仓库更多 Skills
verify
Use when a change in __SERVICE__ must be checked before review
work-record
Use when you finished work on a tracker task and it must be recorded in the workspace through a merge request.
task-new
Use to create one story in a stream from the stream profile's story template, link it from its scope screens and open a merge request.
task-decompose
Use to split a stream at the decomposition stage into stories - list scope screens without a story, create the accepted stories and close the stage through a merge request.
task-context
Use to gather the context of a story key or a tracker id - its story, stream stage, scope screens, repositories, decisions, mockups and work records.
repos-sync
Use to update clones of your repositories under repos/ and see their branch, lag and uncommitted changes.