Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 41 additions & 16 deletions lib/required-skills.js
Original file line number Diff line number Diff line change
@@ -1,47 +1,72 @@
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 EvoMap

// A Gene pins a skill it needs as one `preconditions` entry (Evolver 2.0.54 and later):
// A Gene names a skill it needs as one `preconditions` entry, either pinned to a commit and its content digest
// (Evolver 2.0.54 and later) or following a branch (Evolver releases that accept branch references):
// skill:git+https://github.com/owner/repo@<commit>#sha256=<digest>&path=<dir>
// skill:git+https://github.com/owner/repo@<branch>#path=<dir>
// The plugin gives the model no tools, so it names the skill with the Evolver command that installs it. Evolver
// fetches the pinned commit and checks the digest; this only reads which skills there are and where they land.
// fetches the commit (or the branch's latest) and checks the digest; this only reads which skills there are and where
// they land, and accepts a reference only in the shapes Evolver accepts.
const GIT_PREFIX = 'skill:git+';
const MAX_SKILLS = 8;
const ASSET_ID = /^sha256:[0-9a-f]{64}$/;
const PIN = /^https:\/\/[^\s#@]+@[0-9a-f]{40}(?:[0-9a-f]{24})?#(.+)$/;
const REFERENCE = /^(https:\/\/[^\s#@]+)@([^\s#@]+)(?:#(.*))?$/;
const COMMIT = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
const SHA256 = /^[0-9a-f]{64}$/;
const BRANCH_SEGMENT = /^[A-Za-z0-9._-]+$/;
const MAX_BRANCH_LENGTH = 200;
const OUT_DIR = '.agents';

function preconditionsOf(asset) {
const found = asset?.preconditions ?? asset?.payload?.preconditions ?? asset?.gene?.preconditions;
return Array.isArray(found) ? found.filter((entry) => typeof entry === 'string' && entry.startsWith(GIT_PREFIX)) : [];
}

// The directory Evolver installs a pinned skill under: the last segment of its path, or of the repository.
function installNameOf(entry) {
const pinned = PIN.exec(entry.slice(GIT_PREFIX.length));
if (!pinned) return null;
const params = new URLSearchParams(pinned[1]);
if (!SHA256.test(params.get('sha256') ?? '')) return null;
const source = params.get('path') || new URL(entry.slice(GIT_PREFIX.length).split('@')[0]).pathname;
// The same branch names Evolver fetches as refs/heads/<name>: plain characters, no `..`, no empty, dot-led or
// `.lock` segment, and no leading `-`.
function isBranchName(name) {
return name.length <= MAX_BRANCH_LENGTH && !name.startsWith('-') && !name.includes('..') && !name.endsWith('.')
&& name.split('/').every((segment) => BRANCH_SEGMENT.test(segment) && !segment.startsWith('.') && !segment.endsWith('.lock'));
}

// The directory Evolver installs a skill under (the last segment of its path, or of the repository) and the branch
// it follows, if it does not pin a commit. A commit needs a digest; a branch takes none.
function requiredSkillOf(entry) {
const reference = REFERENCE.exec(entry.slice(GIT_PREFIX.length));
if (!reference) return null;
const [, repo, rev, fragment = ''] = reference;
const params = new URLSearchParams(fragment);
// Evolver refuses a fragment key it does not know, so naming such a skill would only hand the model a failing command.
if ([...params.keys()].some((key) => key !== 'sha256' && key !== 'path')) return null;
const sha256 = params.get('sha256');
const pinned = COMMIT.test(rev) && SHA256.test(sha256 ?? '');
if (!pinned && (sha256 !== null || COMMIT.test(rev) || !isBranchName(rev))) return null;
const source = params.get('path') || new URL(repo).pathname;
const last = source.split('/').filter(Boolean).pop() ?? '';
return last.replace(/\.git$/i, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || null;
const name = last.replace(/\.git$/i, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80);
return name ? { name, branch: pinned ? null : rev } : null;
}

/** The lines that tell the model to install and read the skills `asset` pins; none when it pins none it can name. */
/** The lines that tell the model to install and read the skills `asset` requires; none when it names none it can use. */
export function requiredSkillLinesOf(asset) {
const entries = preconditionsOf(asset);
if (entries.length === 0 || entries.length > MAX_SKILLS || !ASSET_ID.test(asset?.asset_id ?? '')) return [];
let names;
let skills;
try {
names = entries.map(installNameOf);
skills = entries.map(requiredSkillOf);
} catch {
return [];
}
if (names.some((name) => !name)) return [];
if (skills.some((skill) => !skill)) return [];
const names = skills.map((skill) => skill.name);
const files = names.map((name) => `${OUT_DIR}/skills/${name}/SKILL.md`);
// A skill that follows a branch is whatever the branch holds at install time, so it is not called pinned.
const heading = skills.every((skill) => !skill.branch)
? `(pinned by this Gene): ${names.join(', ')}`
: `for this Gene: ${skills.map((skill) => `${skill.name} (${skill.branch ? `latest on branch ${skill.branch}` : 'pinned'})`).join(', ')}`;
return [
`Required skill${names.length > 1 ? 's' : ''} (pinned by this Gene): ${names.join(', ')}. Before acting, install ${names.length > 1 ? 'them' : 'it'} and read ${names.length > 1 ? 'them' : 'it'}:`,
`Required skill${names.length > 1 ? 's' : ''} ${heading}. Before acting, install ${names.length > 1 ? 'them' : 'it'} and read ${names.length > 1 ? 'them' : 'it'}:`,
`- Run: evolver skill fetch --asset ${asset.asset_id} --out ${OUT_DIR} --write --force`,
`- Read ${files.join(' and ')} and follow ${names.length > 1 ? 'them' : 'it'} with the steps above.`,
];
Expand Down
18 changes: 18 additions & 0 deletions test/required-skills.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,24 @@ test('a skill pinned at the repository root takes the repository name', () => {
assert.match(requiredSkillLinesOf(root).at(-1), /\.agents\/skills\/report-builder\/SKILL\.md/);
});

test('a skill that follows a branch is named as the latest on that branch, not as pinned', () => {
const branch = `skill:git+https://github.com/EvoMap/gene-skills@release/v2#path=skills/Quest_Gate`;
const lines = requiredSkillLinesOf({ ...GENE, preconditions: [branch, PIN.replace('skills/Quest_Gate', 'skills/report')] });
assert.equal(lines[0], 'Required skills for this Gene: quest-gate (latest on branch release/v2), report (pinned). Before acting, install them and read them:');
assert.equal(lines[1], `- Run: evolver skill fetch --asset ${ID} --out .agents --write --force`);
assert.equal(lines[2], '- Read .agents/skills/quest-gate/SKILL.md and .agents/skills/report/SKILL.md and follow them with the steps above.');
});

test('a branch reference with a digest, a commit without one, an unknown fragment key, or a branch name git could misread names no skill', () => {
const at = (rev, fragment = 'path=skills/x') => ({ ...GENE, preconditions: [`skill:git+https://github.com/EvoMap/gene-skills@${rev}#${fragment}`] });
assert.deepEqual(requiredSkillLinesOf(at('main', `sha256=${'c'.repeat(64)}&path=skills/x`)), []);
assert.deepEqual(requiredSkillLinesOf(at('b'.repeat(40))), []);
assert.deepEqual(requiredSkillLinesOf(at('main', 'md5=x&path=skills/x')), []);
assert.deepEqual(requiredSkillLinesOf(at('b'.repeat(40), `sha256=${'c'.repeat(64)}&path=skills/x&ref=main`)), []);
assert.deepEqual(requiredSkillLinesOf(at('--upload-pack=x')), []);
assert.deepEqual(requiredSkillLinesOf(at('main/../../tags/v1')), []);
});

test('a Gene without a pin, a malformed pin, or an id unsafe for a shell names no skill', () => {
assert.deepEqual(requiredSkillLinesOf({ ...GENE, preconditions: ['skill: knows git'] }), []);
assert.deepEqual(requiredSkillLinesOf({ ...GENE, preconditions: [PIN.replace('#sha256', '#md5')] }), []);
Expand Down
Loading