Agent Skills
› NeverSight/learn-skills.dev
› python-blueprint-authoring
python-blueprint-authoring
GitHub用于为全新或仅含基线的Python仓库生成符合v1锁定架构的review-ready blueprint.md。需验证技能名称、工具链及结构不变量，确保与python-project-init-greenfield兼容，处理歧义并严格遵循章节顺序。
Trigger Scenarios
新建或基线Python仓库需要初始blueprint
在执行前编写或修复greenfield蓝图
Install
npx skills add NeverSight/learn-skills.dev --skill python-blueprint-authoring -g -y
SKILL.md
Frontmatter
{
"name": "python-blueprint-authoring",
"inputs": [
"target repository or project name and proof that the lane is truly greenfield or baseline-only",
"project purpose and baseline scope for Project Overview",
"exact required skill names that already exist in the current library",
"concrete toolchain choices and versions for Toolchain Expectation",
"concrete packages, paths, entrypoints, and other locatable structure for Structural Invariants",
"measurable quality targets and concrete sensing assertions for Quality Thresholds and Acceptance Criteria"
],
"outputs": [
"review-ready greenfield blueprint.md using the locked blueprint v1 section order",
"stop-and-ask feedback when required skills are missing, structure is abstract, or the request is in the wrong lane",
"a contract that python-project-init-greenfield can consume without schema translation or guessed locators"
],
"use_when": [
"a new or baseline-only Python repository needs its first review-ready blueprint.md",
"the task is to author or repair a greenfield blueprint before execution starts",
"the contract must stay inside the locked blueprint v1 shape already consumed by python-project-init-greenfield"
],
"complexity": "high",
"description": "Author a review-ready greenfield `blueprint.md` contract for a new or baseline-only Python repository, reusing the locked blueprint v1 schema already consumed by `python-project-init-greenfield`.",
"risk_profile": [
"ambiguity_sensitive",
"multi_agent_handoff",
"destructive_action"
],
"do_not_use_when": [
"the repository already has meaningful structure, migration pressure, or retrofit conflict surfaces; use python-retrofit-plan-authoring",
"the task is to execute a valid blueprint; use python-project-init-greenfield",
"the task is to review or approve an existing blueprint",
"the request lacks tool choices, verifiable acceptance targets, or locatable structural details that cannot be derived safely from explicit intent or the repository name"
]
}
Purpose
Turn greenfield Python repository intent into a review-ready blueprint.md that python-project-init-greenfield can consume without reinterpretation.
Trigger / When to use
Use this skill when:
- a new or baseline-only Python repository needs its first review-ready
blueprint.md - the task is to author or repair a greenfield blueprint before execution starts
- the workflow needs exact-name
Required Skillsvalidation, concreteStructural Invariants, and explicit stop-and-ask handling for ambiguity - the authored contract must stay inside the locked blueprint v1 shape already used by
python-project-init-greenfield
Do not use this skill when:
- the repository already has meaningful structure, migration pressure, or retrofit conflict surfaces; use
python-retrofit-plan-authoring - the task is to execute a valid blueprint; use
python-project-init-greenfield - the task is to review or approve an existing blueprint
- the request lacks tool choices or verifiable acceptance targets, or lacks package names or other locatable structural details that cannot be derived safely from explicit intent or the repository name; if a package name is derived, record the concrete derived name in the authored blueprint before handoff
Inputs
- the target repository or project name and proof that the lane is truly greenfield or baseline-only
- the intended project purpose and baseline scope for
## Project Overview - exact required skill names that already exist in the current library
- concrete toolchain choices and versions for
## Toolchain Expectation - concrete packages, paths, entrypoints, and other locatable structure for
## Structural Invariants - measurable quality targets and concrete sensing assertions for
## Quality Thresholdsand## Acceptance Criteria - explicit human clarification whenever the request is abstract, contradictory, missing a locatable detail, or routed to the wrong lane
Process
- Confirm lane fit first.
- Use this skill only for new or baseline-only Python repositories.
- If the request is really retrofit planning, route to
python-retrofit-plan-authoring. - If the request is execution or review, hand off to
python-project-init-greenfieldor reviewer flow instead of absorbing those roles.
- Reuse the locked blueprint v1 contract exactly.
- Author only the heading order already consumed by
python-project-init-greenfield. - Do not invent a new section, alias, compatibility layer, or alternate block format.
- Author only the heading order already consumed by
- Validate
Required Skillsbefore drafting the final contract.- Check every named skill against the current library using exact directory names.
- Treat
_versus-, case changes, guessed aliases, and invented placeholders as invalid. - If any named skill is absent, stop and ask instead of normalizing or deferring the problem downstream.
- Write the blueprint in the locked section order:
## Project Overview## Required Skills## Toolchain Expectation## Structural Invariants## Quality Thresholds## Acceptance Criteria
- Write
## Project Overviewas concise human-readable baseline intent.- Summarize the repository purpose and baseline goals.
- Do not hide missing structural decisions behind general prose.
- Write
## Required Skillswith exact current-library names and explicit roles.- Keep each listed skill locatable as
skills/<skill-name>/in the active library. - Preserve an optional marker only as
(Optional)after the exact skill name when truly needed.
- Keep each listed skill locatable as
- Write
## Toolchain Expectationand## Structural Invariantswith concrete, executor-usable detail.- Name real tools, versions, package names, paths, and entrypoints.
- If the request says only “modern layout”, “good defaults”, or similar abstract goals, stop and ask.
- If structural details are contradictory or cannot be located in the filesystem, stop and ask.
- Write
## Quality Thresholdsand## Acceptance Criteriaas verifiable contract surfaces.- Under
## Acceptance Criteria, place a fencedyaml [sensing-assertions]block immediately below the heading. - Every assertion record must include
kind,target, andexpected. - Keep human explanation outside the machine-readable block.
- Under
- Run the authoring self-check before handoff.
- Confirm section order, assertion-block placement, exact-name skill validation, locatable structure, and greenfield lane fit.
- Confirm the draft stays upstream-authoring-only and does not widen into executor changes.
- Stop at
review-ready.- Do not approve the blueprint.
- Hand the draft to reviewer flow once the contract is complete.
Examples
- Positive: Author a greenfield
blueprint.mdfor an empty weather repository that listssense-env-scaffold,python-testing-pytest, andpython-type-hints-strictby exact library name, declaressrc/weather_service/main.py, and puts ayaml [sensing-assertions]block immediately under## Acceptance Criteria. - Negative: Draft a blueprint for an existing repository that needs migration, guess a missing skill as
python_testing_pytest, or writeStructural Invariantsas “use a modern src layout with good defaults”.
Outputs
- a review-ready greenfield
blueprint.mdusing the locked blueprint v1 section order - exact stop-and-ask feedback when required skills are missing, structure is abstract, or the request is in the wrong lane
- a contract that
python-project-init-greenfieldcan consume without schema translation or guessed locators
Validation
Required Checks
- all six blueprint v1 sections are present in exact order: Project Overview → Required Skills → Toolchain Expectation → Structural Invariants → Quality Thresholds → Acceptance Criteria
- every schema v1 field is populated with concrete, executor-usable values; no section is left empty or abstract
- no TBD placeholder or abstract style words (e.g. "modern", "sensible", "clean") appear in any locked field
## Acceptance Criteriastarts with a parseableyaml [sensing-assertions]block immediately below the heading- every sensing assertion includes
kind,target, andexpected - every named required skill matches a real current-library directory name exactly
Quality Checks (best effort)
- naming conventions are consistent across package names, paths, and entrypoints
- toolchain dependency choices are justified or accompanied by rationale notes
## Project Overviewis concise and hides no missing structural decisions behind general prose- sensing assertions cover the main structural invariants declared in
## Structural Invariants
On Soft Fail
- mark blueprint as INCOMPLETE at the top of the draft
- list every missing or abstract section explicitly
- do not block output; deliver the partial draft with gaps flagged so the reviewer can act
Failure Handling
Missing Context
- BLOCKED — if project intent, package name, or key structural decisions are not provided and cannot be safely derived from explicit context, stop and ask before proceeding
- list the specific missing inputs explicitly; do not fabricate locators, package names, or sensing assertions to fill gaps
Ambiguous Requirement
- note the assumption explicitly as a sub-bullet under an existing section of the blueprint (e.g., under
## Implementation Notes) - proceed with best-effort draft using the stated assumption
- flag the assumption clearly so the reviewer and
python-project-init-greenfieldconsumer can evaluate it before handoff
Execution Limitation
- if the schema v1 reference (
references/blueprint-contract.md) cannot be read, note the limitation explicitly in the draft - fall back to the known locked section order and block placement rules embedded in this skill's Process
- do not invent new sections or omit required ones to work around the limitation
Verification
- confirm the section order is exactly Project Overview -> Required Skills -> Toolchain Expectation -> Structural Invariants -> Quality Thresholds -> Acceptance Criteria
- confirm
## Acceptance Criteriastarts with a parseableyaml [sensing-assertions]block - confirm every sensing assertion includes
kind,target, andexpected - confirm every named required skill matches a real current-library directory name exactly
- confirm package names, paths, entrypoints, and tool choices are concrete enough for executor consumption
- confirm greenfield-only lane fit is explicit and retrofit requests are rerouted instead of absorbed
- confirm the skill stays in authoring scope and does not imply executor or reviewer approval
Red Flags
- the request mixes “create the first baseline” with “preserve and migrate these existing files”
- a named required skill does not exist in
skills/ Structural Invariantscontain only style words such as “clean”, “modern”, or “sensible”- acceptance prose appears before the
yaml [sensing-assertions]block - the request tries to make
python-blueprint-authoringchoose execution-time behavior or modify the executor schema
Common Rationalizations
- “The executor can normalize the skill name later.”
- “We can leave the structure abstract because greenfield repos are easy.”
- “This repo mostly exists already, but blueprint authoring is close enough.”
- “The sensing assertions can be added after init works once.”
- “A missing required skill can stay as a placeholder for now.”
Boundaries
- Do not execute the blueprint.
- Do not approve the authored blueprint.
- Do not invent a new blueprint schema or widen the executor contract.
- Do not normalize, alias, or silently replace missing skill names.
- Do not invent package names, paths, entrypoints, tool choices, or sensing assertions when the request is abstract.
- Do not absorb retrofit planning, runtime routing, or reviewer responsibilities.
Local references
examples.md: layered blueprint-authoring scenarios, stop-and-ask cases, and lane-mismatch exampleschecklist.md: repeatable review-ready checks for this higher-risk authoring skillreferences/blueprint-contract.md: locked blueprint v1 section order, block placement, and parser-facing authoring rulesreferences/required-skills-validation.md: exact-name library validation rules, optional-item handling, and blocking missing-skill behaviorreferences/greenfield-lane-boundaries.md: greenfield-only fit rules and rerouting boundaries versus retrofit or executionreferences/structural-invariants-locatability.md: concrete locatability rules for packages, paths, entrypoints, and stop-and-ask triggers
Version History
- e0220ca Current 2026-07-05 21:38
