hassan-mohiddin/freeflow / .deprecated/skill-tooling-pre-rewrite/skills/write-skill
write-skill
VerifiedUse when creating or revising an agent skill.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.7 KB |
| references/activation-boundaries.md | markdown | 2.9 KB |
| references/agent-first-instructions.md | markdown | 3.3 KB |
| references/development-loop.md | markdown | 2.2 KB |
| references/progressive-disclosure.md | markdown | 1.9 KB |
| scripts/lib/skill-author-core.mjs | script | 6.2 KB |
| scripts/skill-author.mjs | script | 2.0 KB |
scripts/lib/skill-author-core.mjs
View on GitHubimport { access, mkdir, readFile, readdir, realpath, stat, writeFile } from "node:fs/promises";
import { constants } from "node:fs";
import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
export function parseSkill(text) {
const match = text.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
if (!match) return { frontmatter: null, body: text };
const frontmatter = {};
const frontmatterErrors = [];
for (const line of match[1].split("\n")) {
const index = line.indexOf(":");
if (index < 0) continue;
const key = line.slice(0, index).trim();
const rawValue = line.slice(index + 1).trim();
if (rawValue.includes(": ") && !/^["'|>]/.test(rawValue)) {
frontmatterErrors.push(`frontmatter.${key} contains ': ' in a YAML plain scalar; quote the value`);
}
frontmatter[key] = rawValue.replace(/^['"]|['"]$/g, "");
}
return { frontmatter, frontmatterErrors, body: match[2] };
}
function inside(root, path) {
const rel = relative(root, path);
return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
}
function inferProjectRoot(skillRoot) {
const skillsRoot = dirname(skillRoot);
return basename(skillsRoot) === "skills" ? dirname(skillsRoot) : skillRoot;
}
export async function resolveSkillPath(input) {
const absolute = resolve(input);
const info = await stat(absolute);
return info.isDirectory() ? resolve(absolute, "SKILL.md") : absolute;
}
export async function validateSkill(input) {
const skillPath = await resolveSkillPath(input);
const skillRoot = dirname(skillPath);
const projectRoot = inferProjectRoot(skillRoot);
const [resolvedSkillRoot, resolvedProjectRoot] = await Promise.all([realpath(skillRoot), realpath(projectRoot)]);
const text = await readFile(skillPath, "utf8");
const { frontmatter, frontmatterErrors = [], body } = parseSkill(text);
const errors = [...frontmatterErrors];
const warnings = [];
if (!frontmatter) errors.push("SKILL.md must start with YAML frontmatter");
const name = frontmatter?.name ?? "";
const description = frontmatter?.description ?? "";
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) errors.push("frontmatter.name must use lowercase kebab-case");
if (!description) errors.push("frontmatter.description is required");
if (name && basename(skillRoot) !== name)
warnings.push(`directory name '${basename(skillRoot)}' differs from skill name '${name}'`);
if (!/^#\s+\S/m.test(body)) errors.push("SKILL.md body needs a top-level heading");
const links = [...body.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)].map((match) => match[1]);
const linkedResources = [];
const linkedDependencies = [];
for (const link of links) {
if (/^(?:https?:|#)/.test(link)) continue;
const target = resolve(skillRoot, link.split("#")[0]);
if (!inside(projectRoot, target)) {
errors.push(`linked resource escapes project root: ${link}`);
continue;
}
let resolvedTarget;
try {
await access(target, constants.R_OK);
resolvedTarget = await realpath(target);
} catch {
errors.push(`linked resource is missing: ${link}`);
continue;
}
if (!inside(resolvedProjectRoot, resolvedTarget)) {
errors.push(`linked resource resolves outside project root: ${link}`);
continue;
}
if (inside(resolvedSkillRoot, resolvedTarget)) {
linkedResources.push(link);
} else {
linkedDependencies.push(link);
}
}
return {
valid: errors.length === 0,
skill_path: skillPath,
name: name || null,
description: description || null,
lines: text.split("\n").length,
linked_resources: linkedResources,
linked_dependencies: linkedDependencies,
errors,
warnings,
};
}
export async function inspectSkill(input) {
const validation = await validateSkill(input);
const text = await readFile(validation.skill_path, "utf8");
const { frontmatter, body } = parseSkill(text);
const signals = [];
const weakPhrases = ["consider", "ensure", "leverage", "try to", "be mindful"];
const foundWeak = weakPhrases.filter((phrase) => body.toLowerCase().includes(phrase));
if (foundWeak.length) signals.push({ level: "advisory", code: "weak-verbs", detail: foundWeak });
if (frontmatter?.description && !/\bwhen\b|\buse\b/i.test(frontmatter.description)) {
signals.push({
level: "advisory",
code: "activation-boundary",
detail: "Description does not state when the skill applies.",
});
}
if (/^\s*(?:>\s*)?(?:\*\*)?(?:Status|Readiness)(?::\*\*|\*\*:|:)\s*/im.test(body)) {
signals.push({
level: "advisory",
code: "status-in-active-body",
detail:
"Move authoring readiness metadata to an eval artifact, report, task record, tool result, or delivery response.",
});
}
if (validation.lines > 120)
signals.push({
level: "advisory",
code: "active-body-size",
detail: `${validation.lines} lines; inspect whether conditional depth belongs in references.`,
});
const root = dirname(validation.skill_path);
const topLevel = await readdir(root);
return {
...validation,
resources: topLevel.filter((name) => name !== "SKILL.md").sort(),
signals,
claim: "Static inspection reports structure and wording signals only; it does not prove activation or behavior.",
};
}
export async function initSkill({ name, root, description }) {
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw new Error("Skill name must use lowercase kebab-case");
const destination = resolve(root, name);
await mkdir(destination, { recursive: false });
const skillPath = resolve(destination, "SKILL.md");
const title = name
.split("-")
.map((part) => part[0].toUpperCase() + part.slice(1))
.join(" ");
const text = `---\nname: ${name}\ndescription: ${description ?? `Use when an agent needs the ${title} behavior.`}\n---\n\n# ${title}\n\n## Job\n\nState the smallest behavior this skill must change.\n\n## Rules\n\n- Replace this placeholder with direct, agent-first instructions.\n- Add references or scripts only after a measured failure proves they are needed.\n`;
await writeFile(skillPath, text, { flag: "wx" });
return {
skill_root: destination,
skill_path: skillPath,
status: "draft",
files: ["SKILL.md"],
};
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |