happyskills 0.50.0 → 0.51.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.51.0] - 2026-05-25
+
+### Added
+
+- **`list --json` now splits unclaimed on-disk skills into `data.drafts[]` and `data.external[]`** (`cli/src/commands/list.js`, `cli/src/utils/skill_scanner.js`). Drafts are skills scaffolded by `init` — they have a HappySkills-shaped `skill.json` (non-empty `name`, valid-semver `version`, `type` of `"skill"` or `"kit"`) and a `SKILL.md`, but no entry in `skills-lock.json` yet because the user hasn't published. External skills are genuinely foreign — they have a `SKILL.md` but no manifest or a foreign-shaped one, and they require `convert` before they can be published. Each draft entry includes `{ name, description, version, type }`; external entries keep the existing `{ name, description }` shape. Human output gains a `draft (unpublished)` row label and a closing hint pointing at `happyskills release` so the principal sees what to do next without having to read the docs.
+- **`is_happyskills_shaped_manifest()` exported from `cli/src/utils/skill_scanner.js`** — small predicate that other call sites (e.g. `happyskills-publish`'s pre-flight) can use to classify a found-on-disk skill the same way `list` does.
+
+### Rationale
+
+Spec 260522-02: when a user scaffolded a skill with `npx happyskills init` and immediately asked an LLM agent to "publish it", the previous `list --json` output reported the skill under `data.external[]` — the same bucket used for genuinely-foreign skills. Routing skills (notably `happyskills-publish`) read this as "external, must `convert` first", inserted a redundant `convert` step into the happy path, and surfaced the words `external` and `convert` to a user who had created their skill with the official tool five minutes earlier. That violated the mission's principal-surface promise of "no unexplained jargon" and "consistency over novelty". The CLI fix is a data-layer split (`data.drafts[]` vs `data.external[]`) so every consumer — routing skills, human output, future tooling — can tell the two states apart at the source. The companion routing-skill fix lands in `happyskills-publish@0.5.0` (in the same monorepo change set), which now reads `data.drafts` and routes drafts straight to `release` without ever mentioning `convert` or `external` to the user.
+
 ## [0.50.0] - 2026-05-24
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "0.50.0",
+	"version": "0.51.0",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/commands/init.js

@@ -133,7 +133,7 @@ const run = (args) => catch_errors('Init failed', async () => {
 		print_info(`Linked to: ${agents_result.agents.map(a => a.display_name).join(', ')}`)
 	}
 	console.log()
-	print_hint(`Edit these files, then run ${code('happyskills publish')} to share.`)
+	print_hint(`Edit these files, then run ${code(`happyskills release ${final_name} --workspace <slug>`)} to publish.`)
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 module.exports = { run }

package/src/commands/list.js

@@ -51,16 +51,23 @@ const run = (args) => catch_errors('List failed', async () => {
 
 	const [, disk_skills] = await scan_skills_dir(base_dir)
 	const managed_names = new Set(managed_short_names)
-	const external_skills = (disk_skills || []).filter(s => !managed_names.has(s.name))
+	// Unclaimed skills (on disk, not in lock) split into two coherent buckets:
+	//   - drafts   → scaffolded by `init`, HappySkills-shaped skill.json present.
+	//                Publish/release pick these up directly — no `convert` needed.
+	//   - external → genuinely foreign (no skill.json, or foreign-shaped).
+	//                `convert` is the path to bring these into the managed set.
+	const unclaimed = (disk_skills || []).filter(s => !managed_names.has(s.name))
+	const draft_skills = unclaimed.filter(s => s.is_draft)
+	const external_skills = unclaimed.filter(s => !s.is_draft)
 
 	// Scan agent-specific dirs for skills placed directly in agent folders (not symlinked from .agents/skills/)
-	const all_known_names = new Set([...managed_names, ...external_skills.map(s => s.name)])
+	const all_known_names = new Set([...managed_names, ...draft_skills.map(s => s.name), ...external_skills.map(s => s.name)])
 	const [, agent_orphans] = await scan_agent_orphan_skills(AGENTS, is_global, project_root, all_known_names)
 	const orphan_skills = agent_orphans || []
 
-	if (managed_entries.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
+	if (managed_entries.length === 0 && draft_skills.length === 0 && external_skills.length === 0 && orphan_skills.length === 0) {
 		if (args.flags.json) {
-			print_json({ data: { skills: {}, external: [], agent_orphans: [] } })
+			print_json({ data: { skills: {}, drafts: [], external: [], agent_orphans: [] } })
 			return
 		}
 		print_info('No skills installed.')
@@ -123,13 +130,19 @@ const run = (args) => catch_errors('List failed', async () => {
 			}
 			skills_map[name] = entry
 		}
+		const drafts = draft_skills.map(s => ({
+			name: s.name,
+			description: s.description || '',
+			version: s.version || null,
+			type: s.type || SKILL_TYPES.SKILL
+		}))
 		const external = external_skills.map(s => ({ name: s.name, description: s.description || '' }))
 		const agent_orphan_list = orphan_skills.map(s => ({
 			name: s.name,
 			description: s.description || '',
 			agents: s.agents
 		}))
-		print_json({ data: { skills: skills_map, external, agent_orphans: agent_orphan_list } })
+		print_json({ data: { skills: skills_map, drafts, external, agent_orphans: agent_orphan_list } })
 		return
 	}
 
@@ -153,6 +166,11 @@ const run = (args) => catch_errors('List failed', async () => {
 		rows.push([display_name, data.version, source, status_label, enabled_label])
 	}
 
+	for (const s of draft_skills) {
+		const type_label = s.type === SKILL_TYPES.KIT ? `${s.name} [kit]` : s.name
+		rows.push([type_label, s.version || '-', 'draft', 'unpublished', '-'])
+	}
+
 	for (const s of external_skills) {
 		rows.push([s.name, '-', 'external', 'installed', '-'])
 	}
@@ -175,6 +193,10 @@ const run = (args) => catch_errors('List failed', async () => {
 		console.log()
 		print_info(`${ahead_count} skill(s) ahead of lock — bumped locally, not yet published. Run publish when ready.`)
 	}
+	if (draft_skills.length > 0) {
+		console.log()
+		print_info(`${draft_skills.length} draft(s) ready to publish — run ${code('happyskills release <name>')} to ship.`)
+	}
 }).then(([errors]) => { if (errors) { exit_with_error(errors); return } })
 
 module.exports = { run }

package/src/integration/cli.test.js

@@ -379,7 +379,7 @@ describe('CLI — --json: success responses use { data } envelope', () => {
 // ─── --json flag: existing commands use { data } envelope ─────────────────────
 
 describe('CLI — --json: existing json commands now use { data } envelope', () => {
-	it('list --json returns { data: { skills, external } }', () => {
+	it('list --json returns { data: { skills, drafts, external } }', () => {
 		// Run in a temp dir with no lock file — produces empty result
 		const tmp = make_tmp()
 		try {
@@ -388,14 +388,51 @@ describe('CLI — --json: existing json commands now use { data } envelope', ()
 			const out = parse_json_output(stdout, 'list --json empty')
 			assert.ok('data' in out, 'should have top-level "data" key')
 			assert.ok('skills' in out.data, 'data.skills should exist')
+			assert.ok('drafts' in out.data, 'data.drafts should exist')
 			assert.ok('external' in out.data, 'data.external should exist')
 			assert.ok(typeof out.data.skills === 'object' && !Array.isArray(out.data.skills))
+			assert.ok(Array.isArray(out.data.drafts))
 			assert.ok(Array.isArray(out.data.external))
 		} finally {
 			fs.rmSync(tmp, { recursive: true, force: true })
 		}
 	})
 
+	it('list --json classifies init-scaffolded skills as drafts, foreign-shaped ones as external', () => {
+		// Two on-disk skills, no lock file:
+		//   - "my-draft"   has a HappySkills-shaped skill.json (init-style)
+		//   - "my-foreign" has only SKILL.md (foreign / hand-rolled)
+		const tmp = make_tmp()
+		try {
+			const draft_dir = path.join(tmp, '.agents', 'skills', 'my-draft')
+			fs.mkdirSync(draft_dir, { recursive: true })
+			fs.writeFileSync(path.join(draft_dir, 'SKILL.md'), '---\nname: my-draft\ndescription: a draft skill\n---\n\n# my-draft\n')
+			fs.writeFileSync(path.join(draft_dir, 'skill.json'), JSON.stringify({
+				name: 'my-draft',
+				version: '0.1.0',
+				type: 'skill',
+				description: '',
+				keywords: [],
+				dependencies: {}
+			}))
+
+			const foreign_dir = path.join(tmp, '.agents', 'skills', 'my-foreign')
+			fs.mkdirSync(foreign_dir, { recursive: true })
+			fs.writeFileSync(path.join(foreign_dir, 'SKILL.md'), '---\nname: my-foreign\ndescription: a foreign skill\n---\n\n# my-foreign\n')
+
+			const { stdout, code } = run(['list', '--json'], {}, { cwd: tmp })
+			assert.strictEqual(code, 0)
+			const out = parse_json_output(stdout, 'list --json mixed')
+			assert.strictEqual(out.data.drafts.length, 1, 'should have exactly one draft')
+			assert.strictEqual(out.data.drafts[0].name, 'my-draft')
+			assert.strictEqual(out.data.drafts[0].version, '0.1.0')
+			assert.strictEqual(out.data.external.length, 1, 'should have exactly one external')
+			assert.strictEqual(out.data.external[0].name, 'my-foreign')
+		} finally {
+			fs.rmSync(tmp, { recursive: true, force: true })
+		}
+	})
+
 	it('search --json usage error returns { error } not raw text', () => {
 		const { stdout, code } = run(['search', '--json'])
 		assert.strictEqual(code, 2)

package/src/utils/skill_scanner.js

@@ -1,9 +1,25 @@
 const fs = require('fs')
 const path = require('path')
 const { error: { catch_errors } } = require('puffy-core')
+const { valid: valid_semver } = require('./semver')
+const { SKILL_JSON, SKILL_TYPES } = require('../constants')
 
 const SKIP_ENTRIES = new Set(['.tmp', '.DS_Store', '.install.lock'])
 
+// A disk-resident, unclaimed skill is a "draft" when it has a HappySkills-shaped
+// skill.json next to its SKILL.md — i.e. the file `init` already produced.
+// "HappySkills-shaped" means: a non-empty `name`, a valid-semver `version`, and
+// a `type` of "skill" or "kit". This is the minimum surface `release`/`publish`
+// can pick up on a no-lock-entry first publish without an intermediate `convert`.
+const is_happyskills_shaped_manifest = (manifest) => {
+	if (!manifest || typeof manifest !== 'object') return false
+	if (typeof manifest.name !== 'string' || !manifest.name.trim()) return false
+	if (!valid_semver(manifest.version)) return false
+	const t = manifest.type
+	if (t && t !== SKILL_TYPES.SKILL && t !== SKILL_TYPES.KIT) return false
+	return true
+}
+
 const parse_frontmatter = (content) => {
 	const match = content.match(/^---\n([\s\S]*?)\n---/)
 	if (!match) return null
@@ -44,9 +60,25 @@ const scan_skills_dir = (base_dir) => catch_errors('Failed to scan skills direct
 		const frontmatter = parse_frontmatter(content)
 		if (!frontmatter || !frontmatter.name) continue
 
+		// Detect whether this skill has a HappySkills-shaped manifest. If yes,
+		// callers can classify it as a "draft" (scaffolded by `init`, not yet
+		// claimed in the lock) rather than "external" (genuinely foreign).
+		let manifest = null
+		try {
+			const raw = await fs.promises.readFile(path.join(dir, SKILL_JSON), 'utf-8')
+			manifest = JSON.parse(raw)
+		} catch {
+			// No skill.json — genuinely external. manifest stays null.
+		}
+
+		const is_draft = is_happyskills_shaped_manifest(manifest)
+
 		skills.push({
 			name: frontmatter.name,
-			description: frontmatter.description || ''
+			description: frontmatter.description || '',
+			is_draft,
+			version: is_draft ? manifest.version : null,
+			type: is_draft ? (manifest.type || SKILL_TYPES.SKILL) : null
 		})
 	}
 
@@ -129,4 +161,4 @@ const scan_agent_orphan_skills = (agents, is_global, project_root, known_names)
 	return [...by_name.values()]
 })
 
-module.exports = { scan_skills_dir, scan_agent_orphan_skills, parse_frontmatter }
+module.exports = { scan_skills_dir, scan_agent_orphan_skills, parse_frontmatter, is_happyskills_shaped_manifest }